httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Igor Galić <i.ga...@brainsware.org>
Subject Re: Docs are demotivating, confusing, bloated and worthless
Date Wed, 06 Oct 2010 16:03:17 GMT

----- "Dirk" <noisyb@gmx.net> wrote:

> Compare
> 1) http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
> with
> 2) http://www.workingwith.me.uk/articles/scripting/mod_rewrite
> (unrelated to me)

Referencing an earlier thread on this ML:
  http://mail-archives.apache.org/mod_mbox/httpd-docs/200912.mbox/browser

This kicked of a BIG... uh.. rewrite of the rewrite docs.

This currently resides in the /trunk/:

 http://httpd.apache.org/docs/trunk/rewrite/


> 1) is demotivating, a textual desert, has no copy&paste-ready
> examples

If it's demotivating, then you're probably the wrong person to
administrate servers. Systems administration are a multitude of
complex, daunting tasks. Reading documentation is the usually the
easiest thereof.

I do agree that some parts of the documentation are a desert.
They haven't been touched in years, are outdated, written by
developers for developers.

I'm a big fan of examples which illustrate the use of something.
But I'm not a fan of copy&paste-ready examples in authoritative
documentation, because this means to everybody that they have
the official charter to shut off their brain.
That, again, is in systems administration a bad idea.
 
> 2) starts with "A simple mod_rewrite example" so that you at least
> know what, the fuck, mod_rewrite is about...
> 
> 
> I can click on *any* module in the apache docs and have to crouch
> through a text desert to find out what i am looking at...


The documentation of every module is built up the same:


Summary:
a short summary of the module

General topics,

Module's Directive synopsis

This, again is built up the same for each Directive:
(here's the example from RewriteBase)

Description:	Sets the base URL for per-directory rewrites
Syntax:	        RewriteBase URL-path
Default:	None
Context:	directory, .htaccess
Override:	FileInfo
Status:	        Extension
Module:         mod_rewrite

Some of those don't make sense for all Directives.
Not all directives can be overridden in .htaccess, for instance..
When you click Description/Syntax, etc.. you'll get an
explanation of what it means.


> Check out the php documentation on php.net... there is no substitue
> for it.. since it is awesome... well.. there is w3schools
> who also cover php.. but php.net docs are still superior...

puuh... the PHP docs...
One of the things I like about the PHP docs is the ability to post
comments -- that's really missing in the httpd documentation.
One of the things I don't like about the PHP docs is the ability to post
comments. Some of those really make me cringe..

We have a wiki space:

  http://wiki.apache.org/httpd

It's a bad replace for comments... but...


> then go and look for apache docs... there are millions of subsitutes
> that try to fix what is wrong with your documentation...

.. given the fact that this is a public mailing list, and given the 
fact that the wiki is publicly accessible too, I think much better
way to fix what's wrong with our documentation would be to contribute
to it with patches or articles on the Wiki.
After all, this is an Open Source project.

> i consider this to be a constructive critique... if you don't get it
> you dont get it...

Thank you very much for your critique, Dirk.
 
> Dirk

bye,
i

-- 
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message