-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 I try to keep my mouth shut about this as much as I can, but when you take a stance as definite as this... [entirely focusing on 'documentation' outside the realm of the original issue]
Simon Kitching wrote: > 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. My take on "non-funded open-source projects" is that they are *not* done because someone needs a tool. They are done because someone needs a tool AND wants to let "the world" take part in developing and using - it. If it were just because someone needed a tool, you'd look to your hard drive and find all those tools you have developed over the years - most if not all with no documentation. The second it becomes a "project", documentation goes with it. To state that a USER community cannot "demand" (hoping "demand" here is used more as "feels there should be", not "Developers! Write user documentation or else!") user documentation is utterly ridiculous. Projects rise and fall based on user documentation. Not all, maybe not most - but the more complex the project is, the more likely it becomes that user documentation is a "must have" for success outside the core developers of it. Should functionality be delayed for it? Not always - but sometimes, yes. Write a little documentation on how to use it and developers won't have to spend as much time answering the same questions on the mailing list. Ounce of prevention and all that. > > 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. This always strikes me as an "open source" oddity. If there's ever a question about "open source", the answer "read the code" always pops up. What I fail to understand is why, although someone may be a developer - a Java developer - and possibly a very good one, they are naturally "in tune" with a project, its coding styles, how it works and where to go in the code to fix something. This is where "the user is a developer" doesn't mesh. Just being a developer doesn't mean you're a maven/<insert project> developer. Therefore, wanting to USE a piece of software should mean being able to USE it without going to code to see how. That said... True statement. Nothing is being hidden. > > 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. I couldn't agree more. > > 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. On a roll here - although I'd replace "often" with "definitely". What would be truly beneficial would be to have someone IN CHARGE (as much as certain people are "IN CHARGE" of certain parts of the code) of providing USER documentation for each release. A developer? Sure. But NOT a core developer that "just knows". > > 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*. Okay. Off that roll we were on. Although I agree with everything here, the implication is that there isn't USER documentation until afterward. Tutorials, How-To's, advanced user documentation? Sure. The sooner the better, yes. But documentation evolves as much (coincidentally sometimes) as the code. The key to successful usage of a project, however, is the user's ability to *cough* USE it. Having Hibernate in there struck me as their documentation has been pretty good from the beginning - FOR USERS. Don't as me to go in to developer documentation as I'm not, nor have I any interest in becoming, a Hibernate developer. [another good example of USER documentation would be Spring]. > > 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. Agreed. Users *should* contribute what they can. But I'd give a mint to the guy that destroyed the Wiki's ability to function as true "documentation". > > Regards, > > Simon Brian -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDPVtaCoPKRow/gARAj1MAKCFwTSlcwaC/nbvqRSTXyXEMpq+dwCgv4j8 vwm4LpyE09hbrrTqcZM34ak= =oS7o -----END PGP SIGNATURE----- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
