> -----Original Message----- > From: Glenn Nielsen [mailto:[EMAIL PROTECTED]] > Sent: Monday, September 30, 2002 6:18 PM > > I would tend to agree with the above, those writing the code > either don't > have the inclination or time to write up good documentation.
In my mind, these developers should be shot. Or at least confined to a tiny little box for an extended period of time. Or maybe just put in charge of a large data center running their software, and their email and cell phones the only contact info on the 24/7/365 call list. Not to rant, but any developer, open source or not, that writes code but fails to provide good or better documentation at the same time is a poor developer, regardless of their technical skill, and regardless of their commitment or uncompensated participation. I'm no developer, but even I know that documentation is key...I probably spend 60% of my sys-admin time writing recipes and docs for other people to descibe what and how I did the things I did in the other 40%. I think that the argument that the developers "don't have time" is a cop-out, especially under the Apache style of development and release schedules. There's no pressure to meet release dates in that mode of development, so time is technically unlimited. I would say it's more "don't have the inclination because documentation isn't as cool as code and my ego gets more of a boost from writing the latest whiz-bang feature or finding a bug in some other guy's code than it does writing a doc that explains how to perform an installation". Which is a shame. Besides, isn't Java self-documenting? ;) > Have you looked at the latest docs for Tomcat 4.1? Much > better jk documentation, > existing docs updated, and even some new documents at: > > http://jakarta.apache.org/tomcat/tomcat-4.1-doc/index.html > I've been all through them, they're pretty much just a rehash of 4.0 docs with a new design template. The new design is pretty, granted, but that's a far cry from where the docs should be. The connector docs are a little better, but in my opinion they don't cover nearly the amount of information they should cover. If they did, this list wouldn't get 100-150 messages every night. That said, I would gladly participate in any documentation project that is started. I could contribute several hours ( 3 < time < 10 ) each week. > > Glenn > John -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
