Maintaining documentation in Markdown

Markdown can be a great tool for maintaining large documentation projects of any kind. There are simple and not-so-simple ways to create the output, but the basic idea is always to maintain the source documents in Markdown format. It provides an easy way to update and maintain multiple output formats and a centralized repository of information that’s easily shared, community editable and ready to pass on to new participants.

There are quite a few ways to work with such a system. I’m going to outline a few that I’ve used, but I know there are plenty more. Feel free to add your own favorites in the comments.

VoodooPad

VoodooPad from Flying Meat is a great desktop wiki that is Markdown-friendly and can output multiple formats, including websites (for intranet or internet publication) and PDF documents for distribution.

As an example, the TextMate Blogsmith Bundle documentation site is entirely generated and maintained in VoodooPad using Markdown. It’s built with an older version and doesn’t take advantage of all the capabilities, but it works.

The latest incarnation of VoodooPad includes a “Collections” feature which lets you organize the output in multiple ways, allowing you to create a more linear document that is more of a chapter-based guide and less of a wiki. Of course, it’s perfect for wiki-type documentation as well.

Procedure

1. Write in Markdown and take advantage of the automatic wiki linking
   • Use aliases on documents to auto-link based on keywords and not just titles
   • Use “scriptlets” to handle tedious titling and add additional functionality in the document.
2. Use web publish with a custom web ouput plugin¹ to output a website
3. Use PDF publish to output printable docs

Pros

• collaboration/sharing
• all source material contained in one place, and easily portable as a bundle
• automatic wiki linking, programmable functionality
• “Collections” pallette in 5.0 lets you organize chapters
• Relatively easy to customize appearance of output

Cons

• Not as portable as a folder of text, but you can easily export text files for use with other systems

ScreenSteps

ScreenSteps is designed for creating documentation. With a little hacking about in the template system, it’s easy to create a Markdown documentation system within the app. With the online sharing tools and the superb screenshot/annotation tools, it’s ideal for screen-based documentation of all sorts.

Steps

1. Edit in ScreenSteps using Markdown
2. Create an export template that renders Markdown
3. Output PDF, Blog posts and online documentation

Pros

• Easy to update and maintain
• Great screenshot capabilities
• Multiple export options

Cons

• Proprietary storage format

gollum

The gollum wiki system from Github is a simple way to make a community (or solo) documentation system. You can use Github to host the wiki or run gollum on its own for a local intranet wiki. It doesn’t lend itself very well to linear documentation or PDF/e-book output, but it’s an ideal solution for group documentation of individual procedures, methods, style rules, etc.

Optionally, you can combine the system with something like nvALT to make editing even easier. Because gollum allows you to store all of your files in a flat folder and create associations between them, nvALT can be a great tool with something like this. nvALT’s inability to handle multiple libraries and folders is a drawback, though. Any text editor that can handle “projects” can take its place and allow multiple folders and hierarchies, if needed.

Steps

1. Store notes as text files in nvALT or a text project in Sublime, TextMate, etc.
2. Default extension “.markdown”
3. Set up Gollum and a .gitignore file in the nvALT/project notes folder
4. Presto, a wiki that can be publicly editable (with version control)

Benefits

• Extremely portable
• collaborative editing
• easily shared
• Easy to secure for internal documentation

Cons

• Outputting print documentation difficult
• Customizing appearance takes more effort

Marked

Marked has the ability to work with “index” files. These can be in Leanpub or mmd_merge format. It basically allows you to work with any folder hierarchy and generate complete documents for output. Combined with a system like gollum (above), it allows for the creation of print/PDF documentation from an otherwise scattered wiki. With custom processor capability, it can handle any form of markup you choose to use and you can script as necessary to handle includes and special document types such as “_sidebar” type inclusions.

Steps

1. Create a folder hierarchy or flat system of Markdown file chapters
2. Use a leanpub or mmd_merge index
3. output PDF or HTML

Pros

• Readily portable storage
• Easy to edit in any editor
• Instant preview of output as you work

Cons

• creating multi-page websites is difficult
• Internal links don’t function in PDF output, due to a webkit bug

Custom build scripts

This is the method I use to generate the online version of the Marked documentation. I have a separate version of it in VoodooPad that I keep in sync, but my ultimate output on that site is currently coming from a build script that generates the internal help system, an online web version and a concatenated Markdown file that Marked uses to generate a PDF version.

Steps

1. Build documentation with Markdown files/chapters
2. Use a build script to read a configuration file, including title information and chapter order
3. include any text processing needed (convert short tags, wiki links, etc.)
4. Generate an index based on the configuration
5. Render the output
   • Use kramdown, maruku, Python Markdown 2, etc.
   • Use Pandoc, HTMLDoc and/or Marked to create PDFs

Pros

• 100% portable
• Infinitely flexible

Cons

• High level of skill required for setup, customization and maintenance

Summary

This takes some experimentation and ultimately your requirements (collaboration, output formats, skill level required, etc.) will determine what’s best for you. Here’s a quick breakdown of the systems listed above.

Ranked elements are 1 (poorest) to 5 (best).

	Portability	Ease	PDF/Print	Web	Collaboration
VoodooPad	2	5	Y	Y	3
ScreenSteps	2	5	Y	Y	3
nvALT/gollum	5	1	N	Y	5
Marked	5	3	Y	Y	5
Build scripts	4	1	Y	Y	5

If you have a Markdown-based documentation system that’s working for you, I’d love to hear about it. If it’s something you want to detail, feel free to contact me and I’d even consider a guest post if you have something you think is brilliant!