Writing Specifications

by Martin Westin in


I have been looking for a good workflow for writing structured text. Techincal specifications and other texts that will eventually become a pdf, Word document or similar. This post will be an overview of what I have that works pretty well. I will use Omni Outliner, MultiMarkdown, Pandoc and Rake in glorious harmony to produce the final document.

What I want is...

  • Good control over the structure
  • Flexible options for the writing environment
  • Automatically generated and updated table of contents
  • Separation of content and styling
  • Version control using Git
  • A painless "build process"

Let's see how I ended up working.

Omni Outliner

I have been outlining, and writing, in Omni Outliner for over 5 years and love it as a general purpose list-maker and organizer. In this context, each item is a heading and the notes for that heading is the body text. This works really well but is limiting on larger documents. I installed Fletcher Penney's MultiMarkdown exporter. This spits out an MD file more of less exactly as I want it. Any Markdown syntax I add into Omni Outliner will of-course be treated as markdown. Bold, italic, lists... all can be marked up in Omni Outliner.

Sadly the iOS version of Omni Outliner is more or less useless to me because of the limited file sharing support. I keep everything in Dropbox and without support for that the workflow becomes very problematic. I hope for this in a new version soon. (Yes I have used DropDAV. No good for me.)

Markdown Editors

I am still evaluating the iOS options. My favorite Markdown app for the Mac, though, is ByWord. It just feels like I am typing fast and am being productive when I am in ByWord.

Another essential (as will become evident soon) app is MultiMarkdown Composer by the aforementioned Fletcher. This app has the killer feature of being able to understand MultiMarkdown and to faithfully export that to many formats. It also has a very nice structure view in the sidebar that makes an OO-refugee feel more at home.

You can also do the trick of exporting you Markdown back to OO by exporting OPML from MMC and opening that again in OO... great stuff. Let's say that again: Using OPML as the file format allows me to instantly jump back and forth between MultiMarkdown Composer (for writing long form) and Omni Outliner (for structuring the document). Shuffling sections (chapters) around has never been easier.

The Multi in Markdown

MultiMarkdown is best explained as Markdown with a few things added to it to better support things that I have found I need in technical documents. One main feature is support for internal references allowing me to reference a section elsewhere in a large specification. E.G. "This uses Feature X which is described in [Common UI Features][]" Those brackets generate an internal link to that section and the extra brackets even allow be to be more casual in my naming of the reference and put the actual heading name inside the second pair of brackets.

Getting It Into Word, or not

I have found a good workflow where I can completely avoid using Microsoft Word. It has been a big win for me to be able to instead use a toolchain more familiar to a software developer.

If you really want to end up in Word

MultiMarkdown Composer does not handle internal references when exporting to a Word document. You have to do a round-trip into Libre Office first if you want to keep those. Yes Libre Office. OpenOffice.org couldn't open the file MMC exported. Neither could Pages or Word itself. NeoOffice cost money these days and I had no desire to pay just to try this one thing.

You open this Flat Open Document and immediately save it again as a Word document and it is ready for Word. The version I downloaded crashed every time when saving a modern Word docx document. Saving as the older doc format (for Word 2003) worked. Good Times™

Pandoc Pipeline With Rake

If you are not a Ruby developer you are probably wondering how I ended up writing about gardening. Rake is actually framework in Ruby to run tasks or macros. In this context it allows you to write pretty advanced automation for converting your Marcdown texts into formatted pdf documents with table of contents, nice design and all sorts of good stuff.

Pandoc is a document format converter. It can take Markdown, for example, and turn it into html, pdf and even a word document. Notably with a little help it can give you a pretty solid E-book build process by taking the pdf and processing it into Epub and Mobi formats for iPads and Kindles respectively.

My rake task locates all markdown documents in a certain folder and processes them all using Pandoc finally outputting nice looking pdfs in a separate folder.

Standing On The Sholders of Giants

I have based my Rake and Pandoc pipeline heavily on that used by Thoughtbot for their E-books. Go to their products page and buy any one of their books and you will get acces to the "source code". That is their entire markdown source text and their rake tools to build the books. Awesome.

Latex, The Not So Fun Part

I leaned heavily on the Latex documentation and examples to hack my way towards to document that looks the way I want. Latex is a horrible nasty markup language for electronic book layouts. It is very powerful but oh so strange and hard to read. If you grit your teeth enough you will be able to style your documents to look pretty much the way you want them to. It is just not a lot of fun but once done that template can be applied to any future document you write.

Version Control

Markdown is just text. Rake is just source code. Latex is also code/text. All this is very well suited to version control. Using Git I get all the conflict resulition help you can ask for and a solid system for tracking changes over time.

Quick Note On Pages

Pages does have a structure mode that looks pretty good. I havent played with it extensively but if you don't want the massive conversion mess described above, then Pages may support enough structure manipulation for you to be happy there... if the iOS integration is to your liking that is. Which is my other reason for going with Markdown.

Disclaimer

Some readers may shake their head and say: I can do all that, and more, in Microsoft Word. Well, good for you. I couldn't figure out that program if my life depended on it. If you know it well and can operate on the structure of your document, move things around, automatically re-assign formatting based on the relative position of something in the overall hierarchy... I'm happy for you and would actually love to know how you work. Personally, I cannot even get Word to properly paste text without going to through the menu using 4-5 clicks.