The best software documentation I’ve ever seen

This blog uses Jekyll and I’ve no plans to change that - Jekyll is a great static site generator with plenty of features and a high level of maturity. Once in a while though I like to freshen things up by changing the theme or editing the one I’m using.

Early in 2021 I started using the Minimal Mistakes theme. This post isn’t to go through how great this theme is, but to point out the fantastic experience I had using it. The documentation for this theme is hands down the best I’ve ever seen for any software - whether a library or language, it is simply fantastic.

Without being too wordy, it covers every feature it supports and gives enough examples to allow quick progress when using it. The configuration page is particularly useful. Although long, it goes through pretty much every setting the theme has, with concise explanations and examples. I systematically went through the entire page, modifying my configuration as I went to achieve the result I desired. This allowed me to discover the full capabilities of this theme (there are a lot) whilst wasting no time and with little-to-no frustration - a rare experience indeed.

Much like design, I appreciate that writing good documentation is a skill that should not be overlooked by developers. Having strong documentation, particularly with an open source project, is a powerful tool to give you the best possibility your project will be adopted as well as ensuring other developers have a good experience whilst trying to contribute. Minimal Mistakes was so trivial to set up and customise that I had no reason to look elsewhere, I can certainly see why it is one of the most popular Jekyll themes. If only this standard of documentation was common with software projects…