I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
James isn’t a writer by trade but is rather a system administrator. For him documentation is a way of ensuring that everything works and our users are happy. He works at iFixIt where they teach everyone to repair the products they use every day. The documentation on iFixIt’s site is all wiki-based and very graphics-heavy. About half the guides are user-contributed.
As James said, good documentation’s worst enemy is bad documentation. Not everyone loves writing documentation and when the love isn’t there the quality can suffer. There’s something different in our brains about docs. We don’t treat them like software and, as a culture, are sometimes numb to documentation. We assume it’s bad and avoid reading it. If we can focus on increasing the quality of docs we can combat this numbing effect.
When you allow bad documentation to linger it drags the quality of the overall library down. A similar effect to the broken windows theory. Bad documentations allows for people to internalize the notion that it’s okay to have crappy documentation. That’s not what we want; we want high standards for quality. As an aside, outdated docs fall in to this bucket as well. Updating them is frequently an easy thing to fix.
The first category that James really, really hates are auto-generated docs. There are three great virtues of a programmer: laziness, impatience, and hubris. Laziness is what drives us to create auto-generated docs. Frequently the result is not worthwhile, not in-depth, and not reviewed with an eye toward user-facing clarity. Javadoc may be a good tool but it’s gone bad. Just because you can do something with a tool doesn’t mean you should. Computers, at their core, suck at writing docs for humans to read.
James then covered the second category of bad docs, those that use overly verbose language. By knowing your audience you can find places to omit needless words. One audience may require great detail while another can do with just an overview. ssh allows for 4 levels of verbosity within the tool itself. What James seeks is a documentation equivalent of that.
The final thing James talked about was mistake-proofing. Humans will always make mistakes, but mistakes don’t always need to become defects in the final product. An engineer at Toyota came up with the concept of deliberately designing mistakes in to your product creation process. The trick is to fix these product failures rather than documenting around them.
After the talk James posted his slides. Check them out.