« Marathon | Main | Condition physique »
December 13, 2004
Less as more
Sun blogger Joey Shen reflects on writing and using documentation in his blog.
Documentation is supposed to be understood instead of showing how smart the authors are.
(Or how clueless.)
Given the way we read documentation, the writer has an uphill battle making himself understood. Sometimes we read the docs before using the object of the documentation. I started Zinn and the Art of Road Bike Maintenance that way yesterday evening.
More typically, we dip into the documentation looking for the answer to a particular question, one we could not find the answer for elsewhere. In other words, we come to the documentation as a last resort and hope to find the answer quickly.
When you're asking Joey directly how something works in his software, standing next to him in his office, you don't mind at all if he starts drawing diagrams on the whiteboard, effectively telling you, "Hang on. The answer to the question you've asked won't make sense unless I tell you all this first." You don't mind because, first, it sure looks like Joey's going to answer your question in the most direct way he can, and second, you have confidence that he wouldn't do all this with you if he didn't care about answering your particular question.
Neither of those conditions holds when we're the readers, piecing together bits of documentation written by somebody who in many cases couldn't have anticipated our questions. We'd rather Google for it. At least that way we don't have to dig through many pages yet come up emptyhanded.
Some people suggest minimalist documentation as a solution. Makes you do less digging. Trouble is, the writer has to be able to anticipate what you're going to ask, which is easier said than done in the real world of complex software.
One partial engineering solution to the problem is to make things a simple as possible (though no simpler). In other words, if what you're creating can work without documentation, do it that way. We might even extend that to say that if what you're creating would be easier for almost all users if it didn't require reading the docs, go ahead and slightly frustrate the 5% of users that really want tweakability. Or make the default behavior something that works for 95%, even if it makes things slightly harder to tweak for the other 5%.
Posted by Mark at December 13, 2004 05:53 PM