On May 3, 2012, at 3:20 AM, André Malo wrote: > Yes. Answering those questions above would be a big help. Beside the > technical > answers we should also point the people to the mailing list to ask their > questions. > However, I'm also inclined to say, that if we're not able to use our own > self-documentation properly, we're doing something very wrong. And it's not > very much. Just a few pages. No offense to anyone, but I'm pretty frustrated > by the "I would contribute, but I don't bother to get some community context" > attitude floating around.
Oh, I don't know about that. I think that we should indeed lower the bar to contributing to the docs. I don't think it should be a requirement to learn about XML, XSLT, SVN, or Ant in order to say "wouldn't that sentence flow better if you said ..." Besides which, the "community context" should be one of welcoming, not one of "go read the documentation for our documentation before you can tell us we misspelled peony." I've been contributing to the documentation for 12 years, and I still find http://httpd.apache.org/docs-project/ to be ... well, kind of embarrassing. One shouldn't need to be a programmer, or even particularly a geek, to contribute a documentation fix. You'll note I say fix, not patch, because I don't feel that the ability to generate a patch is a particularly important one in a documentation expert. The ability to *write* is, and if we scare off a writer with a poorly-written page, then we've done us and them disservice. Anyways, enough philosophy. Here's what I'm planning to do in the near future. The "whodunnit" portion of http://httpd.apache.org/docs-project/ doesn't need to be half of the front page. Unless someone strenuously objects, I'd like to move that to a /docs-project/contributors.html page, and, if possible, look in SVN to make it actually reflect reality a little better. The top section of the page (the bit with the "Documentation Project" header) is largely filler text. It's nice, but it doesn't really contribute much. The "How to get involved" section is the one that matters. http://people.apache.org/~humbedooh/contribute.html does a better job of saying it, and that's a good starting point. But I'd really like to emphasize in some friendly way that if folks want to fix something, it's adequate to send us email, or put a fixed copy of the HTML somewhere, or send us a letter, or ... you know, generally get that fix to us in any way that they can. The community context comes from the way we welcome that contribution. If the welcome is "no, we need a valid patch in valid XML against the latest HEAD revision", then they'll never stick around long enough to find out what the community context is. Anyways, that's my soap box. Less talking, more doing. Shosholoza, as they say. -- Rich Bowen rbo...@rcbowen.com :: @rbowen rbo...@apache.org
