! Update see below
π !
The problem
Writing my most recent
blog post I realised that collaborating on writing posts on SAP Blogs is harder than it could be. Even though I wrote the post by myself, I wanted to show drafts to others before actually publishing, to make sure I was writing comprehensible content. Sharing these drafts however was more tedious than I thought it would be as the only feasible option I found was to "print" the draft page as a PDF file and distribute that to my reviewers. Thinking a bit more about the issue I also remembered that when collaborating on a previous blogs post, this was also a challenge since the different parts had to be joined somehow.
My solution
To tackle the solution I split the problem into two parts: enabling a helpful collaboration on writing a blog and transferring the collaboration results into a published blog on SAP Blogs.
Collaboration
Pondering about how to enable a helpful a helpful collaboration quickly brought me to the usage of git, a version control system most (if not all) developers already know and use β most of them on a daily basis. Using git as the collaboration platform for this use case was a no brainer in my mind so since it comes with a plethora of helpful tools when collaborating on artefacts β even if those artefacts are not code.
When thinking about git as the solution to the collaboration problem a lot of git features come to mind which can be helpful in writing a blog β especially if it's a bit more complicated and maybe requires a few iterations until it is final:
- version control and branching to test ideas or roll back to previous states
- traceability to see who made which change (and why if they use meaningful commit messages π )
- issue tracking to invite feedback or correction suggestions
- pull requests to invite open collaboration on the blog content
- kanban boards to track progress (e.g. if you're working on a series or multiple complicated blogs at the same time)
- access control on the repository (viewers, contributors, groups, β¦)
- β¦
Now that we've established (or rather I decided
π ) that git is the way to go we can move on the the topic of bringing it together in an SAP Blog post. If you want to dive further into the topic of git β especially if you're not a programmer β I'd recommend looking into
this blog.
Transferring results to SAP Blogs
I got a little ahead of my self here: Before we can actually transfer our collaboration results we need to create them first. This bears the question how we'll create the blog since things such as formatting, links and code blocks should be recognised by SAP Blogs. After all we don't want to do the work twice
π .
Thinking about how to solve this problem I quickly realised that using
markdown would be the perfect fit.
Markdown is a lightweight markup language to format plain texts and doesn't require any programming experience. Also there are a lot of visual
markdown editors meaning you don't even need to know how to write
markdown π . The main point is that you can create nicely formatted drafts for your blog which you can collaborate on using the git features. This enables a collaborative workflow similar to what we're (almost) used to now in an environment with e.g. Word and SharePoint.
For technical blogs it's an even better fit as a lot of software projects already use
markdown pages for readmes or even the
whole documentation of their projects. This means that there probably already is a starting point one might want to include in a potential blog post as well as existing knowledge on how to write
markdown.
Now the only thing left was to actually build the thing and therefore the tech part
π€. Choosing
node.js as the runtime for my transpiler enabled me to build on existing code β namely the
marked package on
npm which provides a lightweight
markdown parser and
HTML output. All I had to do was to add the specific SAP Blogs quirks (code markup, heading style, β¦) and put everything together. The result is ready to be inserted in the text box on the SAP Blogs edit page.
Conclusion
If you want to write a blog now, you can set up a git repo for your blog, compose it in
markdown (or copy the content from your docs
π ) and collaborate on it using the git mechanisms. This also makes reviewing much easier as we can also use tools like issues, pull requests and the built in
markdown preview (e.g. in GitHub). To publish the blog you run the transpiler, copy its result into the SAP Blogs page and replace any picture you might have in there.
Since
markdown supports more features than the SAP Blogs editor (e.g. tables), you might even be able to make more appealing blog posts than you were before
π .
You can find the result and instructions on its usage on
my personal GitHub page. Please feel free to use it for your next blog and give me feedback! If you find something amiss or want to improve / collaborate on this I'm happy to get in contact with you β just use the issue function on GitHub, open a pull request or contact me here.
Happy blogging everyone!
Updates
01.09.2023
More updates on images: another colleague,
gabrielt, contributed to the image part of this project by making it easier to sync your remote and local images! By doing the mapping once you can now reduce the replacement process of images to one initial time! All details can be found in the GitHub readme linked above.
28.08.2023
I updated the mechanism for the images a bit after the insight
wilhelmflo gave me with
his blog. You can now replace the images in the visual editor instead of having to insert them by yourself.
