As far as I know, each package is supposed to have its own documentation. The index page in /doc scan the installed and uninstalled packages and shows links for their documentation pages, but that's about as far as the integration goes. So package documentation is not integrated with acs-core-docs.
If I were you, writing new documentation, I don't know if I'd go with Docbook. In fact, I've thought about converting our acs-core-docs from Docbook to something else several times (and I was the one encouraging ArsDigita to move the 4.x docs to Docbook way back when).
The reasons are simple... Docbook has all the whiz-bang and cool stuff, and a lot of people use it and all that, but it's just very hard to work with. It is very hard to be able to write a document quickly. There are a bunch of tools to install, a bunch of new, very verbose markup to learn, a bunch of settings to a bunch of places that need to be done.
In short, while it does everything one could imagine for documentation, unless you have someone with lots of Docbook experience/knowledge on board, the cost time-wise to climb that learning curve is so steep that nobody does it because nobody has time to and because documentation teams are seen as third-class citizens in the open source world (meaning you are rewarded for pumping out code, but if you pump out documentation that is seems as a clerical job without importance, so no one wants to get involved too much there).
What ends up happenning is that of the handful of people who are ok with being considered third-class citizens, only a few end up getting the courage to climb that learning curve, resulting in less documents or less updating of documents.
So I've thought about moving our documents to a format that's easier to work with, simpler, less complex, without such a learning curve, so that anyone could contribute docs in an easy manner. One of the formats I've thought of is APT (Almost Plain Text) which Ben Adida told me about a while ago.
http://www.xmlmind.com/aptconvert.html
-Roberto
