httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Ruggeri <DRugg...@primary.net>
Subject Re: Error documentation, more thoughts
Date Thu, 22 Mar 2012 01:34:13 GMT
On 3/15/2012 3:36 PM, Rich Bowen wrote:
>
> On Mar 15, 2012, at 4:23 PM, William A. Rowe Jr. wrote:
>
>> On 3/15/2012 3:16 PM, Eric Covener wrote:
>>> I'd just as well add supplementary info to a wiki for the specific
>>> message IDs that require extra discussion.  I've never been a fan of
>>> the massive "messages" publication that's 98% the verbatim error text
>>> phrased three different ways.
>>
>> ...
>>
>> But I can't see an error guide which says;
>>
>>  AP0000 Error resolving host name, did you forget 'ServerName'?
>>
>>    This Error indicates httpd could not resolve a host name from dns
>>    for the configured server ip address.  The ServerName directive
>>    can be used to work around this dns lookup issue.
>>
>> Add words, but to what benefit?  The lookup/list, though would be
>> great if the user quickly wants to find out what AP0000 is in their
>> own native language, even though the AP0000 message in the bug
>> report or blog entry was printed in an unfamiliar language.
>
>
> Yes. Ideally we're talking about only a small percentage of the error
> messages being represented in this documentation.
> Although there are 2000+ error codes at the moment, I would hope that
> we'd have far less than that actually represented in the docs.
>
> Most of our error messages are self-explanatory. The advantages of
> doing this at all are:
>
> 1) Additional help on error conditions that might have several
> different possible solutions.
> Viz: http://wiki.apache.org/httpd/13PermissionDenied
> 2) Localization
> 3) Searches for error code AP0000 resolves to the docs, or a mirror
> thereof, rather than resulting in a hit on the svn server.

I was thinking more about this on my long drive home again today. I
agree fully with Eric's point (I've also fallen victim to this
"documentation" phenomenon).... but at the same time I'm having trouble
trying to strike a balance with documenting "everything" vs "important
stuff".

Following the example Bill used, who's to say that Joe Admin (or even
Joe User who has httpd installed as part of a distro and may not really
understand the basics of how this web thingie works) will know that they
will need a PTR record added to their local (or maybe not!) in-addr.arpa
zone? Who even maintains that zone? Heck, do they know what a zone is?
Maybe that's just a bad example for me because I also wear a DNS
administrator's hat, but the thought in my mind is that we can't always
assume error messages that make sense to you and I (AKA: people who have
seen it several times) will make sense to the user. Don't worry... I get
Bill's point that the user really just needed to add ServerName or a
reverse entry, but hopefully this illustrates something useful.

So, follow my train of thought if you will... I know a lot of this is
still up in the air so I'm brainstorming. Is it terrible to document
every error code on an individual wiki page starting with the error
message in the log and a small blurb saying, "This needs additional
documentation. To help with this effort, do XYZ"? Perhaps doing XYZ is
as simple as flagging the article to let a docs committer know that
someone needs help with that error. Logically following that, we would
start fleshing out the documentation by log severity as already
suggested. I'm also no SEO expert, but I think this kind of organization
would help with scoring hits to individual errors at the same time.


P.S.
Whatever approach for compiling this type of doco is decided, I'm happy
to lend Perl-Fu and time fleshing out details for modules I'm
particularly familiar with (SSL and proxy especially).

-- 
Daniel Ruggeri


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


Mime
View raw message