Personal experience seems to indicate that the best Designs do not need Documentation to be usable, but the worst Designs need pages and pages of Documentation. The heuristic is that the quality of a Design is inversely proportional to the length of the user Documentation.
The problem, of course, is that there’s no guarantee that a poorly-designed product has enough compensatory Documentation. Likewise, someone may have just written lots of Documentation for something that didn’t really need it.
Taken on its own, it’s not perfect, but if you are looking at adopting a product, process, or other technology, you may want to choose the one that, all else being equal, has the slimmest manual.
9 thoughts on “The Relationship Between Design and Documentation: A Heuristic”
That is why I refuse to document anything. The code is self explanatory and self documenting.
If I ever start a new company, the product we sell is going to be a small box with a single button on it. I don’t know what it’s going to do yet, but that’s what it will look like.
bignate, unless it’s Perl 🙂
pebler, I’ve seen that show. That box kills someone you don’t know, then they give it to someone you don’t know. Please don’t make an evil button box like that.
What does this say about Emacs… ?
djwhitt, my heuristic applies to both emacs and vi. A new user, first seeing emacs or vi, would have a slightly better chance of figuring either out than they would landing the space shuttle on manual.
Are you saying that both emacs and vi have bad designs? (I wouldn’t necessarily say otherwise. I’m just not clear whether that’s the point you’re trying to make.)
They definitely have bad UI designs, for the most part, but they are very powerful tools. If they weren’t as powerful as they are, I doubt most people would suffer through the process of learning the UIs 🙂
Agreed. I think in judging design you need to take audience into account. Emacs and vi are not designed for “average” users. Of course, that said you could probably improve usability a lot without hurting power much. Come to think of it that might be the reason Textmate is so popular these days.
Textmate looks pretty cool. I’ll check it out and see how it compares with eclipse.