Don’t Write Documentation¶
| Authors: | James Pearson |
|---|---|
| Time: | 9:40 - 10:00 |
| Session: | http://docs.writethedocs.org/2014/na/talks/#james-pearson-don-t-write-documentation |
| Link: | http://changedmy.name/talk–dont-write-documentation/ |
As you may have guessed by the title, James is not a writer. But the scraggly beard and EFF sweatshirt indicate that he is a sysadmin [for iFixIt], and as such documentation is just about making sure you don’t miss any steps. iFixIt is a wiki-based platform that lets any user write documentation and step-by-step guides to repair anything.
So why shouldn’t you write documentation? Because good documentation’s worst enemy is bad documentation. The programmers who James hangs out with hate documentation; they assume that it’s going to be wrong, so they don’t even try to read it. For example, the image processing library they were using to annotate images had many, many bugs. Upgrading fixed some and introduced others. The take away was that that library is crap. But the take away when we see bad documentation, is that all documentation is bad. We don’t treat documentation like software (where we might think this particular piece of software is crap): we’re numb to documentation.
See also: broken window syndrome. When you see bad documentation, it tells you that lax standards are acceptable for this project or product.
So what sort of documentation is awful?
Autogenerated documentation can be awful.
The Perl “Camel” book is a joy to read, and it instructs us on the Three Virtues of a Programmer.
- Laziness
- Impatience
- Hubris
Laziness is the one that causes pain. Tools like Javadoc are often abused: just because your tool can extract documentation doesn’t mean that the documentation is going to appropriately communicate content to other users.
Poka-Yoke – “mistake proofing”.
A Toyota engineer realized that people will always make mistakes (because we’re human), but mistakes don’t have to become defects. Poka-yoke refers to designing a tool or product in a way that prevents mistakes from becoming defects. (See http://pokayoke.wikispaces.com/ for examples.) The solution to many defects is not documentation, but changing the product or software.