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
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871
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
slive@finance.commerce.ubc.ca
http://finance.commerce.ubc.ca/~slive/
Phone: (604) 822-1871