/ Pratik Mallya

How to write documentation without dying of boredom

TLDR: Write docs in Markdown, watch this video

We use a somewhat obtuse tool called Confluence at our company to document things, both for technical and non-technical stuff. Whenever I would be tasked with writing documentation, it would perhaps be the worst part of my day. Why?

You can see how writing documentation with such a tool feels so amazingly disheartening.

And then I saw this great talk on empowering non-developers to use Git; the premise is basically how the author and his team convinced even the non technical folks to start using Git as a collaboration tool to write content in Markdown, and then use CI/CD to auto-publish the content on merge.

Busy with other things I didn’t pay it much attention, other than posting the link to the talk in a slack channel. But then, the team manager decided to write the team charter as Markdown in Git, and then used a python script to deploy that to confluence, on merge. Aha!

The idea caught on pretty soon and we started moving a large amount of documentation to Git. Writing documentation is so much easier when you follow the same workflow as code contributions. It feels “clean”. You can use Github labels to indicate the stage of your documentation (“draft”, “ready for review” etc.). No need to deal with setting the layouts correctly. We even started moving design docs and other Google Document based content to Markdown. I actually want to write documentation for things that I feel others would benefit from, and that is perhaps the most important benefit.