tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Turner, John" <>
Subject [OFF TOPIC] RE: Documentation
Date Tue, 01 Oct 2002 15:09:28 GMT

> -----Original Message-----
> From: Bruce Williams []
> Sent: Tuesday, October 01, 2002 10:56 AM
> To: Tomcat Users List
> Subject: RE: Documentation
> There is a big difference between writing policy and 
> administrative doc,
> and writing product documentation on a product that has a 
> short release
> cycle. I suppose you could have yearly releases with more polished
> documentation, but the world is just moving faster than that 
> so lighten
> up? :-)

As I pointed out, there is no release cycle in the Apache mode, and there is
no release cycle in open source.  You release when you feel the product is
ready for release, and no sooner.  You're also under no threat of liability
for providing something sub-standard, so there is no incentive to do so
other than laziness or a desire to be the first with the "coolest" instead
of second with the best.  "No time" is an invalid and illogical source developers have nothing but time.  Maybe I'm in the
minority, but on the rare occasions I get to write applications, I'm much
more satisfied taking an extra day or week and delivering 100% of the
package instead of skipping that extra day or week and delivering 70%.

It's a very simple matter to include "good documentation" as a criteria for
judging when something should be released.  Problem solved.  The problem
users of open source experience is that a large portion of open source
developers typically use "it works, there's no docs, but what do they expect
for free?" as a release criteria.  Let's face it...many open source
developers get a kick out of saying "my app had a certain feature before the
app from some-big-company" instead of getting a kick out of "I delivered the
best damn application package anyone has ever seen".  "some-big-company"
typically equals Microsoft, IBM, or Oracle.

Regarding my own docs, I can assure you they're not "policy and
administrative" docs.  Quite the opposite, and in my opinion a recipe for
building and deploying a production server, performing a security lock down
procdure, or any number of other procedures and processes, is usually much
more comprehensive than a document that says "this function does X and takes
these 3 parameters as arguments".  There's a difference between an
explanatory document and a step-by-step guide for implementing a solution.

I'm not knocking open source developers themselves, only their tendency to
avoid providing comprehensive documentation at the same time as providing
the application they developed.  I honestly can't think of a single logical
argument to support not releasing acceptable documentation.  What good is
spending your own time and effort for free to produce something for people
to use if they don't know how to use it and you won't tell them?  It makes
much more sense to have as big a user-base as you can possibly have, and it
gives you a much better return on your time and effort.  One of the best
ways to increase your user-base is not to decrease (or eliminate) the price,
but to help more people understand how to use what you gave them or what is
available to them.


To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message