velocity-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brad Cox <>
Subject How do we win?
Date Tue, 17 Jul 2001 01:55:33 GMT
At 12:15 PM -0700 7/16/01, Jon Stevens wrote:
>This is a perfect example of something I see all the time:
>     If we don't write docs, people complain that there are no docs.
>     If we write docs, people don't read them.
>How do we win?

Since you put it as a question, I'll respond to it as such. Politely, 
which is far from what I feel like doing.

There is far more complex world than implied by such cartesian 
either-or choices. The answer to your question is to avoid such bogus 
choices altogether. The software industry is full of examples of 
software that delights users regardless of whether they read the docs 
or not. Apple, Microsoft and Adobe are particularly well-known 
examples of companies who do this well.

If you want to win, deliver products that *delight* your users 
whether they read the manuals or not. Software that anticipates 
common mistakes and silently prevents them (via menus that only 
contain valid entries) or when that's not possible, describes the 
problem in the user's frame of reference (stack backtraces do not 

If you want to lose, write software that throws NullPointerExceptions 
or segfaults upon the slightest mistake (see mod_jk, Tomcat, and 
Velocity for great examples of this). Then blame the user on public 
listservs for not reading the manual. Better yet, impugn their 
professional capabilities, even call assholes, threaten to throw them 
off the list for even questioning the developers' decision. And so 
forth. If you don't know what I'm talking about, see recent traffic 
on this list.

None of this is rocket science, just common-sense, Jon. Ignore it at 
your peril.
For industrial age goods there were checks and credit cards.
For everything else there is mybank.dom at
Brad Cox, PhD; 703 361 4751

View raw message