Jon,
I modified and did some retouching and updating to the Documentation guide that aD had made, and that's what we've been using. We inherited a lot of Docbook XML documentation and we couldn't just change all that, so that's the format we are using, at least for the core docs.
What I noticed was the the tools for dealing with Docbook SGML are more mature and easier to work with, but since everything we had was in XML, we had to keep it.
What I'm seeing now are packages where only HTML documentation is being done only in HTML, and we're in for big trouble if we start fragmenting things like that.
In one hand I understand that it's an added burden for someone creating a package to learn and mess with Docbook XML, and all the tools involved. But on the other hand, we'll have to come up with a standard at some point. The advantages of Docbook are indexing, output to several formats (SGML makes this easier, with XML it's trickier) including PDF, easy linking, etc.
When you say that "AD's format was a dismal failure and existed only to say they were documented", are you referring to Docbook? Or to the documentation templates they created?
