There’s a truism when it comes to writing documentation - the harder it is to update the documentation, the less likely it’ll be up to date. Most developers consider documentation to be an afterthought - something you create after you make the app. When updates cause a view to change or a button gets relabeled, documentation often becomes out of sync.

Until recently, documentation for Divergent Media apps was created in Adobe Indesign. This had the benefit of being completely customizable and designable - we had total control of fonts, image placement, pagination, and so on. It had the downside of being incredibly time-consuming to update. Additionally, because we don’t use Indesign for other routine tasks, there was a re-learning curve each time we went to update the documentation.

A new approach

We use markdown for nearly everything on our website and many of our internal documents. Blog posts, podcast updates, and even software update release notes are created in markdown and then rendered to HTML for display. It was a natural extension to move our documentation to markdown as well.

While there are many powerful tools for working with markdown, our desired workflow proved a little bit challenging. There were a few critical criteria we needed to satisfy:

  • PDF and HTML output
  • Fully style-able
  • Interactive table of contents
  • Consistent rendering on Mac and Linux
  • Easily installable tools (no custom patches)

After a lot of trial and error, we’ve arrived at a workflow we’re pretty happy with.

The core of our markdown workflow is based on Pandoc, a cross platform markup conversion tool. Pandoc uses LaTeX to style markdown to PDF conversions, which allowed us to customize layouts, font choices and image placement. We’re also able to insert cover pages separate from the markdown content.

Most markdown to PDF options on the Mac utilize Webkit - they create HTML, then render the HTML in Webkit and export that to PDF. Unfortunately, this breaks anchor links, which are necessary for a functional table of contents. Pandoc uses its own PDF rendering, which preserves anchor links.

Pandoc also generates the basic HTML we use for our web-based manuals. A separate HTML template creates the enclosures for the table of contents and the body. Additional styling takes place at page-load, via JavaScript.

Finally, the Bootstrap “Scrollspy” feature provides an interactive table of contents on the web.

How does it all work? Take a look at the ClipWrap manual on the web and as a pdf for an example.

If you’d like more specifics about our workflow, just drop us a line.