Block's Docs Talk.

Warren Block answering questions


In November, KnoxBUG had the good fortune of having the great Warren Block give a presentation about documentation. Most of us, including myself, don't usually think of documentation as an exciting part of the technology world. That's because it isn't really. Documentation is one of those things that we expect to be there, and to be correct. We don't really notice or make a judgment on the quality of documentation until we run into bad documentation and that is what this talk was about. 

What makes documentation bad?

Documentation doesn't have to be incorrect to be horrible. Warren Block talked about three general pitfalls of documentation. Too much information, too little information and information quality. He went through various case studies (mainly live web sites) that illustrated these pitfalls. While experiencing Warren's unique presentation style, I found myself going down memory lane and thinking about all the times I've run into documentation that had incorrect examples, that made too many assumptions about the reader's experience level, that was way too verbose and rife with edge cases in the examples. It wound up being one of the most fun and entertaining talks I've been to. It fostered a new awareness of the importance of documentation.

I took some notes during the talk and assembled a bullet point cheat sheet of some of the do's and don'ts for documentation. In the future, I will consult this list whenever I do any sort of documentation. Even if it's just for myself!

  • Avoid weasel words like "should"
  • Avoid Backreferences "former/latter". 
  • Anticipate the most common questions
  • Make your docs discoverable. Create good navigation
  • Always test examples and procedures on a fresh install
  • Don't show people what not to do in your examples
  • Put warnings before dangerous commands, not after!
  • Strike a good balance between info quality and quantity