httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dirk <noi...@gmx.net>
Subject Re: Docs are demotivating, confusing, bloated and worthless
Date Wed, 06 Oct 2010 16:34:11 GMT
Igor Galić wrote:
>> 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.

so is /has/ to be more difficult to configure apache than writing backends in php? :o

i am sorry... i didn't realize that apache finances itself with consulting...

> 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.

i turn my brain on when the copy&paste-ready example tells me it is worth it... when i
read the docs right now.. i have to use
my brain all the time.. and it is mostly not worth it... which causes stress, aggression and
demotivation... your documentation
is pushing the ring button of my conciousness and when i open the door all i see is bloat..

>> 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.

is this a documentation for the documentation?

>> 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'll have a look.

thank you


Dirk

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


Mime
View raw message