httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Antwort: "About the Documentation" (primarily: prerequisites)
Date Fri, 25 Apr 2003 11:46:33 GMT

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 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.
     "<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:
For additional commands, e-mail:

View raw message