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 

You can find more examples and conversion results on the site examples repository

chronicler-examples/pandoc at master · mikhailidim/chronicler-examples
Sample code for the posts. Contribute to mikhailidim/chronicler-examples development by creating an account on GitHub.