Better documentation through wiki markup

Good documentation matters. What makes documentation good is partly a subjective decision. The remaining part is anything but subjective.

For Power Manager 3.7 the release notes mention that the documentation was improved. What that improvement means is the topic of this blog post.

Perspective matters

Writing documentation for software is tough. As a developer, I view Power Manager through very different eyes than you, a user of Power Manager. I see obvious decisions backed by knowledge of internal details, unrevealed from your perspective. I see an expected workflow for you that may or may not gel with your real workflow.

Experience has taught me that documentation is essential only where it sheds light on a product. This might sound obvious, but the obvious is a good place to start with documentation.

Avoid wasted hours

Too often I have wasted hours of my life trying to get work done and struggling despite following the manual; unlike that stereotypical male, I am happy to turn to the manual before starting a new task or application. Those wasted hours have often ended with the realisation that the manual is inaccurate or plain wrong. Providing documentation that is wrong is worse than providing no documentation, and providing incorrect documentation is not uncommon in today’s rush to market.

Following incorrect documentation leads you down the wrong path. In the end, you are either stranded far from your goal, with many hours of struggling ahead, or left believing the tool you have chosen just does not work. Either way, the tool has failed you.

It would have been better to not see the incorrect manual and instead have felt your way forward through trial and error. A correct manual gets you to your goal faster, but an incorrect manual risks preventing you from ever reaching your goal.

Looking in the wrong direction

Why does the wrong documentation get shipped? Why does documentation not get checked and updated as a normal part of a product’s incremental development?

Writing good documentation is hard for many software companies. We tend to be focused too much on the technology and its implementation, and not enough on you and your experience.

Lessons learned

When we shipped Power Manager 3.5 last January, we introduced a new workflow for creating the product’s documentation. With Power Manager 3.7, this workflow was restructured and refined using the lessons learned during the last year.

Our documentation is written in plain text using a couple of different mark-up notations to apply semantic information. Semantic information is a formal way of saying that some piece of text is a title, where another piece of text is a paragraph. The art of keeping the mark-up to a minimum is the key to a good notation.

I am happy to claim that we took our notation from a well-tested source. Wiki notation is very simple, well defined, and limited.

I have David Vincent to thank for opening my eyes to the beauty of the wiki. I worked with Dave at Toshiba and he taught me a great deal about many of the finer points of being a great software engineer.

Avoid font choice procrastination

The wiki notation constrains the writer to writing. It is difficult to do anything more than write content within a wiki. The notation does not allow for procrastination over presentation, visual tricks, or hours choosing a font.

The wiki notation forces you to think only in terms of useful content and structure. Choices are reduced to how best to structure a document, topic, or paragraph. Putting the focus on the content helps create documentation that is clearer and easier to follow.

Always improving

Power Manager 3.7 is the first DssW product to use the updated documentation workflow. The look and feel of the resulting documentation has been tweaked here and there to improve readability - particularly where the documentation includes AppleScript or shell script fragments. I hope our improved documentation will help you find your way when exploring Power Manager 3.7’s more advanced features.