A couple of weeks ago we launched three product updates. These were updates to Power Manager, Sleep Monitor, and Energy Schedule. The updates make sure our software works seamlessly with Apple’s new Mac OS X 10.5, also known as Leopard.

As usual, we marked the launch with a little celebration. But this was a special launch. Special because it encompassed three products, and because it marks our first launch since Megan and I returned from living in Lyon.

A year in France

Last year Megan and I had to break with tradition. We spent the year travelling and most of our time was spent living in France. The broadband revolution is wonderful, and last year proved my ability to continue to grow DssW while roaming free from a traditional office environment.

Living in France had its down side. It meant foregoing our traditional David Jones’ food court chocolate cake slice.

Surprisingly, finding suitably rich chocolate cake in Lyon was not easy. Thankfully, finding an alternative was easy - and so we broke with tradition and settled for local delights.

Back in Australia

We are back in Sydney, Australia, for a while. Once again, we can shop at David Jones for chocolate cake, but our tradition has been questioned. Never again can we return to David Jones without comparison to the delights of Lyon.

Cadbury’s cupcakes marked our launch

So, Megan and I had some fun and we made Cadbury’s cupcakes. Lots of little celebratory cakes in place of our usual one luxurious piece. Not in the same league as either David Jones or Lyon’s patisseries, but a yummy marker for our three latest updates.

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.

Queen Victoria Building, Sydney

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.

Chinatown entrance, Sydney

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.

Today we launched Sleep Monitor 2.1.2. It is available to buy and download immediately.

A week of power events captured by Sleep Monitor 2

Sleep Monitor 2.1.2 audits and aids trouble-shooting a Mac’s energy and power usage. Sleep Monitor gathers information over days, weeks, and months to build a complete picture of a Mac’s energy use. It records information about battery levels, recharging rates, and periods of sleep, shut down, and use.

Changes in Sleep Monitor v2.1.2

• Fixed relative date bug (Mac OS X 10.5).

Today we launched Energy Schedule 1.0.1. It is available to download immediately.

Energy Schedule Dashboard Widget

Energy Schedule 1.0.1 is a free Dashboard Widget that reveals your Mac’s queued power events. Software applications use power events to aid automation and schedule changes in the computer’s power state, such as waking from sleep or switching off.

Energy Schedule is a great tool for tracking which applications are scheduling what events on your Mac.

I recommend downloading Energy Schedule today, and having some fun scheduling events. Who knows, you might even end up creating an energy saving schedule.

Changes in Energy Schedule v1.0.1

• Improved display of Power Manager queued events.
• Changed font for consistency between Mac OS X 10.4 & 10.5.