Documentation and Safety.

Safety image from the national safety council of Australia.

Safety image (via flashbak)

I recently read the latest book by Gene Kim, the Unicorn Project. Essential reading for anyone involved in building software. It should be on Netflix, with Claire Danes from Homeland in the lead role. In the book Gene mentions the Alcoa story, where the CEO, Paul O’Neill, focused on health and safety to drive organizational change at Alcoa. For details on the Alcoa story, see Charles Duhigg’s excellent book, the Power of Habit. review here.

In the Unicorn Project, the lead protagonist grapples with many challenges, including very poorly documented software and a cryptic software build process. Ultimately, all turns out well.

For software companies, technical documentation serves an obvious primary purpose. It explains how to use your software. Good document saves on support calls and reduce implementation issues. Documentation is not glamorous, but it is goodness. And while we all aspire to software that is intuitive to use, good documentation is part of feature complete.

However, documentation has an important secondary purpose. When customers buy software, they suffer from information asymmetry. How can they know if your software is good quality or not? They can ask other users, and look at reviews, talk to analysts etc, but these don’t always tell the full story. When a software company documents their products well and consistently over a long period of time, it is an effective form of signalling. It provides a window for the customer into your product quality. A organization that cares about documentation is likely to care about elements of the coding process that are less visible. Good documentation, done consistently, is very hard to fake. Just like safety is in manufacturing. Documentation is part of your brand and your culture.

KellyAnn, over at Redmonk, wrote about an offering they have just launched. The Technical Communications Review This is a brilliant idea. It doesn’t just look at your product documentation, but your complete technical communications. I’ll be recommending this service to the software companies I work with.