+1 I think we've been spoiled by the open-source projects that are funded by big companies, that may have paid technical writers. In my use of a lot of other open-source software, such as linux utilities, I've relied on mailing list archives, forums and unofficial How-Tos on blogs of people not connected to the development team.
I believe the crux of open-source is contribution, and so if one wants good documentation, one should think about wrting it himself. This doesn't have to be such a big effort. Replying to mailing list questions or recording your discoveries in a blog are incremental ways to contribute. -- Calen Martin D. Legaspi Sun Certified Enterprise Architect Software Engineering Director, Orange & Bronze Consulting, Inc. President, PinoyJUG - "Developers building community." - http://groups.yahoo.com/group/pinoyjug The Third World Developer Blog: http://calenlegaspi.blogspot.com On 3/7/06, Simon Kitching <[EMAIL PROTECTED]> wrote: > > > First of all, non-funded open-source projects (which is what this is) > are usually done because someone needs a tool *themselves*. That person > clearly does *not* need documentation. If *you* need documentation, > that's not the problem of the person writing the software. In practice > developers do write some documentation themselves; in some cases the > documentation is very good. However it's not something that a user > community can *demand* of the unpaid creators of a tool. And neither can > we users demand that the developers delay releasing functionality they > want because they haven't documented it enough for us to use. > > Secondly, this is open source. If you really want to know how a > particular piece works, read the code. It's the final and official > documentation. Nothing is being hidden from any user of the software. > > Thirdly, documentation is *never* complete. There's always someone who > doesn't understand a topic, or who wants to do something out of the > ordinary. I'd consider your request to package dependencies of a module > inside the jarfile as an example of that. It would be frustrating to see > new functionality kept unreleased because *some* of the potential users > are not able to understand it or want to use it in unexpected ways. > > And fourthly, the developers are often *not* the best people to write > the documentation. For someone who knows all the details of an > implementation it's quite hard to step back and write good introductory > tutorials. > > Just about every successful commercial product ever released has had > books about it published *months to years* after the product was > released. MS-Office tutoruals, RedHat administration guides, Hibernate > "developers notebooks". Continuing the documentation process after the > product is released is *normal*. > > The most important piece is the first, though. As users we shouldn't > demand but instead contribute. Updating the main site directly isn't > possible, but improving documentation via a wiki is. > > Regards, > > Simon > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > >
