httpd-docs mailing list archives

I have been enduring an extended tirade from a disgruntled user
regarding the vhosts documentation. I suppose I could share most of his
notes with the mailing list, but I'm not sure how much good this would
do. His primary points are as follows:
1) There's no step-by-step guide for setting up a virtual host. (I don't
think that I agree with this, but I admit that I have a somewhat
different perspective, having done this a few times.)
2) The documentation does not tell you what you need to do with DNS in
order to get virtual hosts working. (I would argue here that we not only
should not be documenting other products, like bind, but we simply
can't. It's not possible to provide howtos for all of the possible DNS
servers that they might be running, even if we wanted to.)
3) (This one is a little strange, and I'm not sure I completely
understand what he's saying) The documentation is too much focused on
what is possible (ie, as in all the possible configuration directives
for a given module, for example) and not enough on what real server
admins are likely to want to do in an average day. He seems to think
that the per-module documentation, and the lists of directives, are not
useful. (Assuming I'm understanding the point that he is making, I
disagree very heartily, remembering the days when I was new to Apache,
and trying to get it to do things.)
So, while I completely disagree with the points that he is making, I
wonder how many other folks feel this way. Are people really having this
much trouble finding the information that they want in the docs? He
talked at length about the way that the open source world, and in
particular linux (with which he drew some sort of analogy to Apache)
seem to think that users derive "a sort of sexual pleasure from solving
riddles", meaning, I took it, that the documentation leaves you to
figure out most things on your own. He also, as far as I can tell, was
of the opinion that ApacheToday, ApacheWeek, and a variety of different
books, in particular Apache: The Definitive Guide, comprised part of the
documentation, and he somehow expected me to be able to do something
about them. And he made repeated comments about how when he first tried
to set up Apache, in 1997, the documentation was no help to him at all.
Anyways, I thought that I would share these thoughts. I'm not entirely
sure why, since I think that he's way off-base, and, personally, I think
that the documentation has made significant improvements over the last
year or two. But, as Bill mentioned earlier, if people have the
perception that something is wrong, then something probably needs to get
addressed. I'm just not sure what that is. Thoughts, anyone?
--
Rich Bowen - rbowen@rcbowen.com
ReefKnot - http://www.reefknot.org
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org