Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: docs@httpd.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Message-ID: <4FA2440B.3060505@cord.dk>
Date: Thu, 03 May 2012 10:38:35 +0200
From: Daniel Gruno <rumble@cord.dk>
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64;
 rv:11.0) Gecko/20120327 Thunderbird/11.0.1
MIME-Version: 1.0
To: docs@httpd.apache.org
Subject: Re: Proposal to move docs to Apache CMS
References: <201204242006.24835@news.perlig.de> <4FA1B51F.3060206@cord.dk>
 <4FA1BA92.40002@cord.dk> <201205030920.50204.nd@perlig.de>
In-Reply-To: <201205030920.50204.nd@perlig.de>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit

On 03-05-2012 09:20, Andr� Malo wrote:
> Maybe I've missed it (quite possible), but did you ask here on the ML? I've 
> heard a lot about IRC (or other) talks lately about this and that. Things 
> should happen on the list - and not only the conclusions. Maybe we already 
> would have a better self-documentation by now.
> 
Last night was late, so sorry if I started rambling - I tend to do that.

I initially got recruited over IRC, so that's where I have been prone to
ask quick questions about the process of committing docs. Yes, some of
us have been very bad at having discussions off-list, and we really
should improve on that. I must admit, I wasn't fully aware of how things
proceeded, and I wasn't really being nudged by others to start
discussions on the mailing list, but pointing fingers at who did what
doesn't do much for me, so I think it's better to just admit that we
didn't do our due diligence and that the mailing list should be the
preferred place for actual discussions, as it is with this one.

This is also why I insisted, on the topic of highlighting, that people
start replying on the mailing list instead, because I was starting to
get very confused about how things really worked. I'm a new guy to all
of this, and I just in the direction people point at.

> 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.

Perhaps we should emphasize this more in our documentation on how to
contribute, maybe either make up a small guide on which steps are taken
when you contribute or discuss (bullet-point style), or maybe we just
need to change some wordings to make it easier to find (or maybe I'm
just being ignorant). I know (now) that we have documentation on how to
commit, but, just as I see frequently on #httpd on freenode, when asked
to read something, the human mind doesn't always pay a whole lot of
attention to the details, especially if it's "hidden" inside a long
document with a lot of irrelevant information before the bits one needs,
so this should really be emphasized and checked up on when letting new
contributors/committers into the fold.

What I would've liked is some simple guide that says:

- Great, you found a bug/error!
- Check out our repository (here's how to do that)
- Edit the XML file that has the error/missing feature
- Optionally use our build tool to check out the new version of the doc
- use svn diff > something.patch or whichever tool you like
- If you're not a committer, send it to our mailing list docs@h.a.o with
a description of what changed and why.
- If you're a committer, upload it to trunk, notify mailing list if it's
a major change, let people review it, and if okay, backport it to 2.4.
- Quick questions on IRC or other off-list methods is fine, but any
actual discussion and review must take place on the mailing list.

With regards, however off-topic this reply may be,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org