Technical documentation is so much more than just a bunch of text characters formed to some words, if you want to do it right.

You need tools for this, that help you throughout the whole process. As always you want to automate those tasks as much as possible. So, first, what is the whole process? It’s not about just writing the content. It needs to be distributed to the reader, meaning its format must be converted, so the user’s device can cope with the document - and that might take a lot of steps.

Before delving deeper into this, let’s start with the first thing to get right, before even writing the first word of text. The intended audience of your documentation already tells a lot about the requirements.

• Source code documentation: Think like JavaDoc, doxygen or jsdoc. Short and concise, so you can take a quick look while developing.
• Reference documentation: The Elasticsearch reference docs are a good example here. Great if you know what you search for, includes a lot of examples. Useless, if you are a novice and would like to get up and running.
• Guides: Again, Elasticsearch - The definitive guide serves as a great example here. It is the accompanying guide for a reference documentation, that is extremely long and explains are the needed topics in order to make the switch from novice to professional in a certain topic (well, at least in theory). Though other types of documentation are often used while developing, this one is definitive also an offline medium, meaning you might want to create a book (physical or ebook) out of it.
• Special documentation: Sometimes there are topics, that require a status overview or the general approach of tackling a problem domain and needs to be explained somewhat more verbose, than an average blog post would able to. A nice example for this is the Elasticsearch resiliency status page
• API documentation: This is basically a special version of the reference documentation for some endpoints, which also needs to explain all the parameters and should provide reusable examples, even in-browser. Something like Swagger or apiary comes to mind here.
• Technical blog posts: Similar to some kind of special documentation, but need to have the capability to show more than just text, like diagrams and code snippets. Can get pretty long due to diving deep into single topic. Usually used as a reference for a certain topic.
• Presentations: Last but not least, you just might want to deliver a brief overview or deep-dive into a certain feature, when talking to other people. Presentations are very different in look & feel compared to all of the above, but maybe there are ways to reuse the same or at least similar formats to make a point in order to be able to copy & paste examples from your software, while still being visually appealing and different (font size, content on one slides, etc…)

With the exception of presentations, all of the above are usually tied to a version of your software. So, if you want to ensure, documentation is updated, when developing a new feature, make sure documentation and software live in the same branch, so everything is in sync, when you do a new release.

Formats

The first longer document I wrote, was the Securing Debian HOWTO (wow, 16 years ago, crazy how time flies by) which was written in SGML. This was horrible. There are alternatives today, good ones even. So let’s focus, on what possibly is most productive, for the person writing the documentation.

I will merely cover the formats I have the best experiences with, and that is markdown and asciidoc.

Markdown

Markdown is a very simple markup language. It is producing HTML by default and has a very limited set of instructions, that are continuously extended by some implementations. A common example is syntax highlighting by specifying the language the code snippet has been written in.

The strength of markdown - its simplicity - is also the strongest weakness. While it is nice for a blog post like this, a real technical blog post needs more power. Like annotations/markers in code samples or math formula support, which some implementations support, or support for writing books in markdown by using multimarkdown (adding ToC, glossary, index, etc.). Also support for simple diagrams has been added using mermaid.

With all those tools added up to the tool chain, things are about to get more complex again. Also converting into other formats than HTML used to be a problem, but publishing tools like leanpub or gitbook or the swiss-army knife pandoc help with that.

Asciidoc

The right mix between complexity but the ability to still have a pretty simple format is Asciidoc. The greatest strength is the possibility to convert into a ton of different formats like PDF, SGML or HTML, making it really cross platform capable. At least one of the big publishers has been using Asciidoc for some time. It basically has any feature that markdown has, but is an especially nice fit for books, as you can have special blocks (like a warning or an out-of-context information), you can have numbers inside of code samples to refer to them. Also ToC, glossary and listings (and all the other things needed for books) are included.

A very common open source implementation is asciidoctor, which was written in ruby, features some interesting additions like embedding videos and has libraries in a ton of other languages, for example javascript, using the Opal library. More importantly is has support for source code highlighting, markdown style block quotes, see here for more.

Others

Obviously these are not the only formatting languages. If you have ever used the older static site generators like jekyll and octopress, you will have stumbled across textile, which has some similarities to markdown. Another candidate there is restructured text, which has been used in the python space. Along with jade and mustache all of them are preprocessors and thus similar to markdown and merely a matter of taste.

The biggest exception in this space obviously is LaTeX, a high quality type setting system. I wrote my diploma thesis with this, mainly because it produces wonderful PDFs, including a nice ToC, glossary, lists of references, tables, images and bibtex. However producing the output is very tedious (you need to know tex packages even for customizing the font), you may have to run it several times and so forth. I also used it for my CVs, even though I would switch to HTML nowadays I think. Same with presentations, I love the beamer package and the resulting presentations, but it takes a lot of work.

Editors

There are endless possibilities of writing technical documentation. Either you use a generic editor, or specialized applications. I will just introduce a couple tools I have used so far. If you have other interesting tools, drop me a mail to add them.

LightPaper (Markdown)

Before checking out LightPaper I used Mou, both are native osx apps - I do not like tools like dillinger or gists, which are hosted solutions.

At some point in time Mou seemed not really to be developed further (even though it seems to be again), so I tried out LightPaper. It even supports a nice theme to convert to PDFs.

Both are easy and simple editors to get up and running with. You can install both via cask on osx.

Haroopad (Markdowon)

Haroopad the next generation editor for markdown. It has more features than simply producing HTML output. Those features include

• Table of Contents
• Formula support via MathJax
• Footnotes
• Embedding of rich media (i.e. tweets) using captions
• Task lists (great for checking during rolling out software)
• Diagrams using mermaid
• Presentation mode using reveal.js
• Tables

You can check the documentation for all the features or the repository.

I really like haroopad, but it is not yet stable and the presentation mode does not render mermaid or diagram outputs. As soon as this works I am really looking forward and I will try it out for presentations. You can also install it using cask.

Even though haroopad starts to fill a gap, I don’t think it is a software I would use for writing a blog post.

AsciidocFX

This is a very interesting new tool for writing technical documentation. Based JavaFX, Spring Boot, Nashorn and Asciidoctor.js it is an editor, that supports not only writing Asciidoc but also allows you to write books, including mobi, epub and pdf formats. In addition it supports more than just Asciidoc

• MathML
• PlantUML
• FileSystemTree
• GraphViz
• Charting (pie and area charts)
• Admonitions (part of asciidoc)

It features a nice and exhaustive documentation on github. Also there exist some books that have been written using this editor.

Atom

Atom is one of the new kids on the block. One of the nice features is its possibility to write plugins and easily install them. The Asciidoc plugin has a neat preview functionality. Even though I would not start up Atom for writing pure technical documentation, it is nice to have built-in plugins for better documentation, in the same editor used for programming.

Tools

This chapter is more about the infrastructure to write books or complete documentation instead of short texts (with the exception of static site generators, which can basically be used for anything).

gitbook

gitbook is a command-line node.js tool, that helps you creating nice looking books. It supports markdown and asciidoc (even though asciidoc feels somewhat limited right now and a second class citizen, I could not get even syntax highlighting support to work with asciidoc).

It is really easy to get up and running

npm -g install gitbook
gitbook init
gitbook serve
gitbook build
gitbook pdf
gitbook mobi
gitbook epub

Most notably you need to have calibre installed to create ebooks. I really like the produced HTML of gitbook, as it looks nice. gitbook also supports plugins, like support for mathjax, comments, disqus and many more, see the plugins page.

If the asciidoc support improves, this is a strong candidate for future usage.

git-scribe

git-scribe is a small set of tools on top of the git command, that makes it simpler to write technical documentation. To get up and running and see a sample book simply do this:

gem install git-scribe
# Check if all needed parts are installed
git scribe check
git scribe init testbook
cd testbook
git scribe gen all

The different formats look pretty nice, the HTML is not awesome, but sufficient for technical docs and you can tweak it. Also, by using kindlegen it produces nice .mobi books.

One thing: The last commit is from early last year, so not sure how actively this is maintained.

Static site generators

Now to one of my favourite tools: static site generators. I think the time of dynamic platforms like drupal or wordpress for small sites or weblogs is over. Just create all the content upfront and let it serve by an nginx or apache web server. Technical documentation/blog posts are both a perfect fit for static site generators. You can have it easily embedded in your website and have a neat design, while being able to generate documentation easily.

One of the great things about static site generators is, that there are so many of them. You can check sites like static site generators or StaticGen to get an overview about the hundreds of static site generators, dozens for any language.

I’d like to highlight to projects here in particular: Harp and Hubpress.

Harp is a node.js based static site generator, that allows you to easily create a static sites. Installation is pretty quick

npm -g install harp
harp init static-project
harp server static-project

harp supports markdown, jade, ejs, coffeescript, sass, less. When you want to run create HTML sites, you can simply run harp compile and copy the created content over to a website. I use harp for this blog as well as for the devcampmuc website as it makes my life much simpler. If I wanted to write huge technical blog posts or very exhaustive, but still nice looking docs, harp would be my first choice. On top of that the harp developers create surge allowing you to push your content to CDNs, for free (see the github repo).

The only missing part of harp is support for asciidoc. Unfortunately the library used for preprocessing is not really extensible with external modules and the authors do not have to seem any intent of making it like that in order to get rid of the dozens of pull requests to support any preprocessor. Once this and live reload support is added in core, harp is going to be completely awesome. I also did a presentation on harp a couple of months ago, in case you are curious.

Another interesting project to fill the asciidoc gap is hubpress. The approach is to clone the hubpress github repo and then use the browser to push data to that newly created repository, so no local installation of anything is needed. The whole idea and concepts behind that look really need, takes you 10 minutes to get up and running.

Other helpers

These are just a couple of other helpers I found, that you may find useful. I cant comment too much on them due to the lack of experience.

• epub: epubquicklook, adds quicklook support for epub format and can be installed via cask
• epub: epubcheck, a tool to validate epub files, can be installed via brew
• epub: epub-to-pdf, epub to pdf converter, can be installed via cask
• epub: Writer2Epub, an openoffice extension to directly create epub files
• epub: sigil, a multi-platform epub editor
• Markdown: MultiMarkdown, an extension to make it easy to write books with markdown (ToC, glossary, etc)
• Markdown: vim-markdown, highlighting support for vim
• Markdown: kramdown, a ruby markdown library with some extensions
• Markdown: qlmarkdown, quicklook markdown renderer, can be installed via cask
• Markdown: Markdown service tools, collection of osx services to make markdown handling easier
• Markdown: hashify, allows to embed whole documents in the URL for easy sharing
• Markdown: gitprint, easily print GitHub markdown
• AsciiDoc: arc42 templates, couple of template to ease creation of architecture documentation
• Other: quarto, another toolchain to create books, which I havent looked at yet

Publishing

If you want to produce a professional book in order to sell it, publishing is the last step. You need to think a lot about, if you want to have the professional editing of a book, but not make a lot of money out of it, or if you prefer to use a very lean publishing platform and decide about the price by yourself. Whatever you do, make sure some other technical experts take a deep look at your book, before you publish it. If possible, make sure, that the other people are native speakers, this makes a big difference for any techbook.

These are a just a couple of platforms I came across, while writing this blog post. I do not have any particular preference or experience with either of them as a book author, so take this with a grain of salt.

leanpub

One of the well known lean publishing platforms on the web. I already bought a fair share of books and I love the fact that the buyer can set the price him/herself (given a certain range from the author). As far as I know most of their platform supports markdown, or more specifically markua. Leanpub does not create ISBNs for their books, so you cannot sell your books via other ebook platforms, like amazon. But that’s where platforms like lulu come into play, which is also recommended by leanpub. They also create real paperbacks of your ebook, so make sure it looks nice, in addition of selling them via the ebook platforms.

gitbook

Gitbook is not only providing a nice tool chain of writing books, but also takes care of publishing it, creating ISBNs and simplifying the boring tasks like accounting and taxing, even though this seems to be tailored to the US market for now.

Others

Obviously, if you are into tech books, there are a couple of well known publishers, that you could ask, if they are interested in the topic you write about. Also I know about several books, that started on lean publishing platforms but then bigger publishers asked if they can actually publish that book, which is a pretty nice accomplishment.

Among the more known tech publishers are companies like O’Reilly, Manning, Pragmatic Bookshelf, Carl Hanser, dpunkt, Addison-Wesley, Apress, Galileo, Wiley, Packt, Entwickler.press - and for sure tons of others.

Missing: Collaboration features

One of the things all of the above platforms were missing, was the collaboration part. If you got an editor persuaded to take a look at your book, you don’t want him to use gitbook and run everything locally, you just want that editor to fix your stupid mistakes and annotate the corresponding text instead of creating pull requests or whatever. An interesting platform for this seems to be Penflip. Whoever integrates with such a platform, will win this battle - and I hope it happens soon.

Presentations

The last part of technical documentations are presentations. At some point in time you usually stop showing some boring documentation, but you need people to use your product and motivate them to read docs. This is what presentations are good for, either by kind of evangelizing your product or by showing off some certain features.

Again there a tons of different approaches for presentations. I really like the approach of latex beamer, which I used a lot in the past (like here), but at the end it just takes too much time, if you want to create presentations in a timely manner.

This usually brings us back to the good old desktop presentation tools like keynote, powerpoint and impress. While I do not like this for deeply technical presentations (no syntax highlighting out of the box, lots of font/size changes needed, typography usually sucks because of too many options for people, the average slide template is ugly), I usually use this, because my design and CSS skills prevent me from doing web based presentations that resemble my company’s corporate identity.

For web-based presentations there are really nice tools like reveal.js, deckjs or shower. I used reveal.js as well as shower already and I really like them. I try to become a better member of the web in the future and create more presentations with this. This also makes sharing with existing documentation and cross-referencing so much easier. The good news is, some platforms don’t forget about presentations, so AsciidocFX will soon have support for presentations. The same applies to haroopad’s presentation mode, which just needs some more time I guess.

One of the biggest problems with web based presentation is the creation diagrams. Luckily things like mermaid started to solve this problem, but there are several image generators on the web, that allow for nice images, for example yuml, which produces neat images like this one:

Last but not least, there seems to be one commercial desktop app, that uses markdown and solves one of the biggest problems of desktop based presentations: lack of themes. Deckset tries to help here. Also it claims it has nice PDF support, which is obviously very important as well for any web based presentation toolkit.

Summary

As you can see, technical documentation is quite a topic, if you view it from different angles. Most importantly, make sure, you stay somewhat consistent and make it easy for everyone to constantly edit and improve the documentation, otherwise it will just become an unmaintained outdated pile of bytes (see, like source code).

Personally even though asciidoc is the superior format, I still like markdown a lot, because the tooling around it seems to develop much faster. But I really hope, that both are here to stay.

That said, if there are more awesome tools, or I completely wrote wrong things, please drop me a note or ping me on twitter and I will update this page.

Back to posts