Tuesday, October 18, 2011

Documentation Bootstrap

I am a fan of good documentation—I feel it's the most undervalued component of many projects but I haven't been able to develop a reliable process to:

  • Collect information
  • Format it
  • Keep it up to date

This is my attempt to come up with that process.


I want to edit my documentation in vim. I like it because it's an extremely lightweight and focused tool for text editing. My .vimrc file is


Markdown is a lightweight markup syntax that avoids the annoying open/close brackets. You can get the syntax extensions for vim from here.


I chose Blogger because it is already integrated with my Google Apps Premier account. I needed something basic and reliable. Documentation is divided into two areas—articles hosted by Blogger and articles hosted on my wiki. We'll begin by setting up documentation on Blogger and then use that to host documentation for setting up the wiki. The wiki will, in turn, host documentation the rest of the server stack.


References to BitBucket code are included via BitBucket's embed function. Note—replace the revision number with default to always pull down the tip version.


Code snippets can also be included via gist on GitHub.


Pastebin is also supported:


We will occasionally need to display equations. There are several options including using the utility available here. Or you can use MathJax by adding the following to your page template:

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

I haven't decided which LaTeX method I prefer.


I store all of my articles on Dropbox ~/Dropbox/blogger/content. I'm not convinced that my articles belong in revision control--I don't see myself branching and merging articles. Dropbox provides revision histories.


The original Markdown article must be processed by Pandoc before it can be published to Blogger. I run the following command.

pandoc --no-wrap "${docname}" -o "${tempdoc}"

The output file ${tempdoc} contains the final version that is consumed by Blogger.


My goal is document, start to finish, the steps need to build and deploy our server stack. This includes

  • Building a new machine with Ubuntu LTS
  • Installing well-known services
    • DNS
    • DHCP
    • LDAP
    • Postfix
    • Samba
    • VirtualBox
  • Installation and configuration of servers
    • Wiki
    • Zenoss

The process for deployment is:

  • Build services on a local virtual machine.
  • Test services with other local virtual machines.
  • Deploy to staging environment.
  • Run staging tests.
  • Deploy to production.
  • Monitor.

1 comment:

David Prager Branner said...

Erratum "Pastbin" -> "Pastebin", surely.