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-unsubscr...@httpd.apache.org For additional commands, e-mail: docs-h...@httpd.apache.org
