Error code documentation

[Rich Bowen <rb...@rcbowen.com>]

Please consider this just a first-draft brainstorm, dumped directly from IRC discussion, and not thoroughly thought through. I'm looking for suggestions that make the least amount of work for everyone. And of course I, along with various other people on the docs@ list, are volunteering to do the bootstrap work here.

Having error codes is a huge benefit to our users, and we would like to avoid creating unnecessary work in maintaining the docs for them going forward. The real value is in the how-to-fix-this documentation that would accompany more complex error conditions.

There's been some discussion over on docs@ about the best way to tackle the error code documentation. It's a bit of a daunting task, and we want 
to be sure that it gets done in a way that is sustainable going forward.

Solutions that have been suggested are:



* A foo_errors.xml file that accompanies any source code foo.c file that contains one or more APLOGNO's

Might look something like
<error>
<logno>00653</logno>
<message>Something bad happened</message>
<description>More details go here</description>
<url>http://more.info/</url>
<module>mod_rewrite</module>
</error>

Advantages: Easy to parse. File is right there when you're editing the source. Easier to maintain than one gargantuan errors document. Easy to update by non-programming documentation folks who can just open the xml file and augment the description and URL after the other basics have been provided. Easy to auto-generate the basics from the source. Easy to translate (foo_errors.xml.fr, foo_errors.xml.de).
Disadvantages: Dozens of additional files laying about in the source tree. Can put them elsewhere, but that reduces the chances that someone will think to edit it when they edit the source.



* Doxygen-style comments in the code. Docs regenerated from this when changed.

Advantages: Right there in the source when you need it. Easy to parse
Disadvantages: Harder to do multiple languages. More intimidating for non-programmer types to get in there and update descriptions. Lots of additional prose in the source code.


* We maintain everything over in the docs tree, either in one gargantuan file, or in smaller files that in some way reflect the structure of the source tree.

Advantages: Docs are where they belong, rather than cluttering the source tree.
Disadvantage: Out of sight, out of mind. Error descriptions don't get updated when new errors are added.



--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org