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. 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. 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. 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. 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. Thanks for your concern! - Brett --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
