nginx documentation

[Gregg Reynolds]

Hi List,

I just discovered nginx last week and I've already jettisoned lighttpd
in favor of nginx.  Very nice piece of work!

I've begun writing a detailed and thorough set of man pages for nginx.
 Well, a pair of them, anyway, nginx(8) and nginx.conf(5).  I've taken
a different approach from the English wiki, though, in the way the
material is organized.  To take one simple example, the stuff on the
wiki is organized by module.  Nothing terribly wrong with that, but
it's developer-oriented.  Ordinary _users_ of the software don't care
about modules; for them it's better to organized things by functional
category (or more generally, according to the mental model the user is
likely to have of how a web server functions).  So I'm starting out
with Principles of Operation (in loving memory of IBM's old POPs
manuals for System/370), to go in nginx(8), with a companion reference
manual on the syntax and vocab of the configuration manual.

One result of this approach is that directives are organized into
functional areas, e.g. Process Configuration, Networking Config, Msg
Handling, Dissemination to Responders, etc.  One interesting thing is
that modeling the processing in terms of Responders to whom messages
are distributed leads to the notion that the default static file
server can be construed as just another Responder, the FSR (FileSystem
Responder).  So the idea is that a simple static page server always
implicitly routes messages to an implicit "fsr":  fsr_pass, just like
it routes some messages to a fastcgi Responder (fastcgi_pass) and
others to a proxy Responder (proxy_pass).  By the same token, blocked
urls, exceptions, redirects can be construed in terms of an implicit
"Exceptions Responder".

I've got a ways to go before the stuff is "publication ready", but I
think I've got enought to solicit feedback and collaboration.  What's
the best way to proceed?  I could post to the wiki, post to my own
website, or email to anybody interested.

Nginx deserves excellent documentation.

-gregg