So, what this discussion has pointed out to me is that, as usual, I am wrong ;-)
I still think that, for the short term, the right thing to do is to commit the by-type core.html index and remove the alpha one. However, in the long term, the modules docs (including core.html) should be a reference only. For a reference, an alpha index seems the best way to go. What gets us from the short term to the long term? Well, I think that there needs to a separate doc for each overall topic that provides a unifying discussion of all the directives of that "type". For example, there should be - Process Creation - Authentication & Access Restrictions - Configuration Files - Environment Variables - HTTP response headers - Logging etc. Each document provides a discussion of the topic, and provides LINKS to all the directives (in various modules) that apply to that topic. The Apache docs already have a little bit of this: The Virtual Hosts docs and the Content Negotiation docs are examples. Of course, it is a huge amount of work to do all this, and it won't get done all at once, but I think it is the way to go. All this other work that I have been doing is basically just serving to cover up for the lack of real task-oriented docs. It is better than nothing, but it is really not the correct way to go. I am grafting a task-oriented structure onto what should be the reference part of the docs. So, two questions: - Do others agree with my diagnosis? - Does anyone want to volunteer to take on one or more of these "unifying" documents? I don't think they need to be long and complicated. Rather, they just need to mention all the directives that apply with a general description of what they do, and provide some examples where appropriate. -- Joshua Slive [EMAIL PROTECTED] http://finance.commerce.ubc.ca/~slive/ Phone: (604) 822-1871
