Pandoc: My Missing Tool
Now, when everything in IT is a code, it is only natural to treat documentation as a code and use the same code management and delivery techniques as the source code. There are plenty of "languages" to produce documentation and tools to deliver it to the end-users. I recently found a tool that closes the "deployment" gap: static or printable content generation.
I use text formatted documents whenever I have an opportunity; for instance, you are reading this document, powered by Ghost engine. I have used standalone Wiki-based sites for knowledge management. I have done my best trying to use Markdown-based text in Microsoft SharePoint and Oracle WebCenter Portal. A long story short, all those attempts were painful, limited, and mostly failed since smartphones were expensive geek toys. Time's past and my first Data Science course with HelloWorld R-flavored Markdown report revitalized my interest in this area. The idea of having a text that you can read, execute, and publish was so exciting.
The way was long and winding, but I found my almost ideal tool - Git* flavored markdowns. All advanced systems offer Wiki/Markdown support on all tiers and page publishing capabilities so that you can keep your documentation close to your source code and use it as a reporting platform. I said "almost" because you still need a hard copy of your documentation with all the bells and whistles from time to time. Unfortunately, one thing never changes - horrible printing support by all browsers, and this rule has no exceptions. It does not matter how good-looking your page is; it will be more or less crippled as soon as you hint Ctrl-P.
Finally, I have found the Pandoc a great tool to generate good-looking, clean HTML5 documents, printable-ready PDF documents, and even presentations.
It supports a multitude of input and output formats; you can customize output results with CSS-based themes. The cherry on the top: you can run pandoc from a command line and could be integrated into your CI/CD pipelines or Ansible playbooks.
# Generate PDF document with pandoc utility
pandoc --from=gfm+smart \
--output my-out-document.pdf print-my-document.md
You can find more examples and conversion results on the site examples repository
mikhailidim