On Mon, 2006-03-06 at 18:36 -0700, Brad O'Hearne wrote: > Simon Kitching wrote: > > >Documentation is always last for developers :-). As it happens, however, > >it is the area that *users* can productively contribute back to a > >project. > > > > > Aside from documenting "things I found along the way", I disagree. First > of all, you have to have the information to produce documentation. > Acquiring this information requires the time of the developers -- there > is no reason for them to be dictating to someone, just write the > documentation. If the users knew the information already, the need for > documentation wouldn't be so dire. Second, relying on users for > documentation guarantees that documentation will always be an > after-the-fact effort. It should never be this way. Third, with the > already pointed-out pace of change, the documentation is virtually > guaranteed to always lag behind current feature and be inaccurate. > > For a product released to the public, open source or not, documentation > should be there, accurate, and clear. The only reason for poor > documentation in any project is choice. Its just a reflection of the > level of excellence to which the project aspires -- and this is any > project, not just this one. The problem is that people have in this > equation in their head: > > code == product. > > This is inaccurate. The real equation is: > > code + documentation + support == product > > Look at it this way, and there would be less focus on bells and > whistles, and more focus on documentation and support of the product.
I don't agree at all. 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]
