Documenting in multiple formats

It is our sworn duty as software developers to make sure that our software is accompanied by good documentation.

One of the challenges attached to this task is that the said documentation is needed in different formats. Ie

  • HTML for web
  • Docs for business guys
  • PDF for clients/consumers
  • Latex Scientific community etc.

A common solution to this problem is simply to write the Docs in word and paste it to all the other formats. This however goes against the DRY (Don’t Repeat Yourselfy) principle.

Thank fully a well known OOP pattern comes to mind. Specifically MVC (Model View Controller).

Now I bet you never think of MVC over and beyond frameworks however it is actually quite a useful pattern. In our case the documentation is our model the various output formats is our views. For the controller part we have to introduce a new piece of software. Pandoc.

Pandoc is a utility that can be used to convert files from one format to another. See Pandoc

With our swiss knife of conversion we are faced with a storage problem. That is how can we store the documentation. While this is something that can vary based on your own preference, I strongly recommend markdown. This is because markdown provides you with formatting tools without tying you down to any particular enterprise and even more importantly it is very easy to write and read.

Assuming that you have followed my advice, now you only need to write your documentation once in markdown and then run a convert to get all other formats.


pandoc documentation.md -f markdown -t html -s -o out/documentation.html
pandoc documentation.md -f markdown -t docx -s -o out/documentation.docx
pandoc documentation.md -f markdown -t pdf -s -o out/documentation.pdf

Now whenever you make a change all you need to do is update the markdown file, documentation.md and then run the conversions.

Happy documentation.

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Published by

jchencha

Software Project Manager