On Aug 25, 2010, at 10:44 AM, James Godrej wrote:
See when some one uses Apache for the first time they are not aware of a lot of things.
The term definition of virtual host itself is quite confusing for newbies.
What is a VirtualHost and why is that used.
How's this for a definition:
This is the examples doc, and references the main VirtualHosts document, which defines what a virtualhost is. We can't repeat the definition on every page, but we can certainly link to the definition when the term is used. I've added this link this morning.
Some one reading the above doc for the first time surely may not be clear.
Having said that if some people are able to understand that does not mean that the doc is really Great.
You do give an example
but among the list of other directives
what is the meaning of word directive with reference to Apache.
Why is a directive being used at all.
Sure there are other pages which do mention what you just said but then again this is as if
I write a module for /proc file system and ask some one to read
and ask the guy to find what seq_files are doing and how are they being used.
Some people may understand some may not.
I'm at a bit of a loss to know how to respond to this.
On the one hand, yes, we need to define our terms.
On the other hand, it's not at all clear to me that it is the responsibility of the Apache httpd documentation to introduce to the reader the concept of a server and the concept of a configuration file. We've rather intentionally stayed away from being a tutorial on system management, editing files, or managing your DNS server, and we'll probably continue to hold that line.
The documentation that you people have does have some technical references.
But I see a lot of blogs forums and links here and there and questions which newbies do suffer
that included me.
Did I answer your question?
Well, a little. You gave two specific examples, one of which I fixed while writing this email, and the other of which I'm really quite uncertain is an actual problem, but I'm willing to see what solutions you propose for it.
We are, always, very welcoming of actual patches to the documentation. General "you suck" kinds of criticisms tend to be received much less gracefully. I'm sure you can understand this, given that I have spent considerable portions of the last ten years writing the documentation, and, so, feel somewhat personally indicted when you say that it is missing "a lot of basic things."
However, I *think* that the direction you're going is that every time we use a basic term we need to define it, and I don't have any objection to that position. That's what we were trying to do with the glossary, and we could probably do a better job of linking to the relevant term in the glossary when a new term is used in a document. I don't object to that at all.