-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Comments inline - and as a preface, they are directed from experience outside (but not too far outside) of the Maven project itself.
Brett Porter wrote: > I tihnk you both make pretty good points on this, even where you might > agree to disagree. Unfortunately I don't have time to reply to this > entire thread, but I couldn't resist this point: > > On 3/7/06, Brian K. Wallace <[EMAIL PROTECTED]> wrote: >>> 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". > > All you are talking about here is a contributing user. There is > nothing stopping any user making that transition, and it would be > welcomed - in fact, the minute we find one we'll hold on and never let > go. It's rare for people to only contribute to documentation, and the > couple who have volunteered to do so in the past have either ended up > preferring to code or getting burned out on it very quickly. Agreed. However, the barrier to entry is actually quite high in this regard from personal experience on open source projects that place documentation below everything else. Contributions only go so far when made by a non-committer. > > By the way, in our projects, its rare for anyone to be in charge for > anything code or documentation. The whole project is responsible for > everything, and people do what they have to for their work or itches > as time allows. As a project, we try and direct people with the > capacity to the right areas. In my usage of "in charge", I wasn't meaning _in charge_, more the "person who specialized in..." - and there are always those. > > Now, we do know there are missing pieces of documentation, and are > correcting that over time. It's also my personal vendatta to write > docs for new functionality at least going forward, and even if they > are brief so that people can expand on them easily. > > The key point of this all was that it is impossible for developers to > know exactly where the holes are now. Rants about documentation are > not going to change anything - *we already know* it needs work, and > always will need work, as you've both said. No offense intended here. I've seen the "give us documentation" and the "we know - we're working on it" threads. My hat's off to all the work that's been done. > > But there are many ways you can contribute: > * file a bug for specific documentation problems. Even if you don't > know the answer, say what you couldn't find or couldn't understand. > * pick up a bug and research that single topic and write a doc for it. > * put together outlines for other people to flesh out. *sigh* yeah... [been trying that approach - not w/ maven (yet) - and met with limited success because of "that's documentation. we're here to work on code" responses (or complete lack of response entirely) - hence my ire over "have users just look at the code" opinions.] > > As for the wiki, we consider that a workspace. Please use it if you > can, and suggest ways to integrate it into the site if you find uesful > things there. Patches are best - APT is no harder to write than wiki > markup. This is possibly the best thing I've ever heard said about a wiki. Taking knowledge from a wiki into documentation is great. Using a wiki AS documentation is where my issue arises. > > Thanks for your concern! > > - Brett -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDP5paCoPKRow/gARAhnpAKCLGpAvAGEROgkBX7WdnfUNPxoNzwCgxt5X z2WVcKUQ9JmZ+xf+K8PrPYY= =gjI9 -----END PGP SIGNATURE----- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
