----- "Dirk" <[email protected]> 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: [email protected] URL: http://brainsware.org/ --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
