Hi Joshua,
> What do you think? I like your text, and find it helpful. > Is it asking to much to insist people know > what an "HTTP status code" is before they read the docs? I don't feel you are actually doing this - all you do is preparing the user that _if_ he/she continues reading the Apache manual without this prerequisit they _may_ experience problems because of these terms that _may_ be used in certain areas of the Apache configuration (but not in all - you may want to make _that_ a little more obvious). I think it is fair what you are doing - and far better than not saying so at all. I always want to make clear who is the 'target group' of some documentation and which skills they will need to read it without problems - and the Apache manual is important enough to invest this amount of work. > <p>This document describes the basic purpose of this manual, > the assumptions behind it, and provides some links to useful > supplementary material.</p> What about some link to the RFC 2616 at this point? (Maybe you already cover this by the Apache internal links - I didn't check that.) > <p>In particular, we assume that readers of this manual:</p> > <ul> > <li>Are familiar with administering their chosen operating system. > This includes manipulation of files and processes, as well as network > configuration.</li> > <li>Have a basic understanding of the technologies of the web, and > HTTP in particular. This includes, for example, understanding what > is an HTTP status code and an HTTP response header.</li> If you think HTTP to be 'the' problem here, then I am quite an 'unusual' Apache 'admin' in your eyes. HTTP for me is some high-level communication protocol where I can write stand-alone applications and what not. I can use an Apache happly via http://127.0.0.1/ and forget about the rest of the world (even if this isn't the was Apache was intended to be used). But networking, this is something totally different - mainly because a CGI application programmer doesn't have administra- tion rights for a whole company network (which normally is some specific office section). And I don't need network privileges to install Apache on some project machine (I don't even need "root" privilege as long as I don't use a well-known port) if all I want is write some application GUI using HTML and CGI (which I am actually doing). This is why I don't have any problems with HTTP (I can just try it out) but struggle severely with the network stuff (Virtual Hosts and the like), which "isn't my business", just like the network people don't think the Apache "application" to be their business. (Am I the only one?) And when HTTP is an issue, the Apache admin would rather need to understand which HTTP headers exist and what they are used for. I didn't have problems to understand the status codes, but it took me some time to understand complex HTTP concepts like caching to some reasonable degree. (The "ETag" is a thing that _could_ be documented more in depth somewhere ... maybe some "HTTP caching Howto" could summarize all aspects of HTTP caching, like ETags and Last- Modified and XBitHack and link to mod_expires and mod_headers and ... even link to mod_cache to make it clear that browser caching isn't server caching nor proxy caching.) So it just depends on the point of view which aspects of Apache are "difficult to understand". If I think of Apache as being some CGI development tool (like a Perl interpreter) then I don't need a lot of net- working stuff (the defaults are fine), and still can read 80% of the Apache manual. And all CGI programmers who just install some Apache on their home PC to check CGI applications before uploading them to their web space are likely to share my point of view. These are the less experienced Apache 'admins', and they will profit most by the article you are just writing. > <li>The manual includes a <a href="glossary.html">glossary</a> that > defines many of the terms we use.</li> In how far can you encourage the reader that he/she will find hyperlinks to this glossary in documents that use terms described there? Do I need to _read_ the glossary, or will I be linked to it 'when appropriate'? (Each glossary term has a link target, so it _can_ be used this way.) Your document is meant to build up some expectation for the reader, and this aspect would be one that encourages me to read on. (By the way: these glossary targets are used like "<dt><a name="accesscontrol">Access Control</a></dt>", thus they display a hovering effect when you move the mouse over them, as if they were links. Using "<dt><a name="accesscontrol"></a>Access Control</dt>" would be the way to avoid this effect, which might mislead the reader who currently expects this to be clickable.) > <p>What if you don't have the prerequisite knowledge? All is > not lost. Here are some suggestions on how to get up-to-speed.</p> You might be a little more encouraging in this section. There are not too many Apache configuration aspects where I actually need HTTP knowledge - especially the 'higher' abstraction levels (cgi, include, autoindex, env, DAV, and everything about path mapping) rather require OS skills (being aware of security and performance and the like - you might want to mention these in your document as well). Basically, I would suggest the user to read on, but return to this section when experiencing problems. Maybe just add one sentence about that, and the rest looks fine for me. Regards, Michael --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
