httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: Proposal to move docs to Apache CMS
Date Thu, 03 May 2012 13:38:32 GMT

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
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org







Mime
View raw message