Re: Documenting Zend (was: zend_parse_parameters)

From: Date: Sun, 09 Sep 2001 22:06:53 +0000
Subject: Re: Documenting Zend (was: zend_parse_parameters)
References: 1  Groups: php.dev 
Request: Send a blank email to php-dev+get-65610@lists.php.net to get a copy of this message 
At 00:59 10-09-01, George Schlossnagle wrote:

The reason I told Jani it had nothing to do with the discussion was that I think that this is wrong...
The reason I disagree is that a large number of people (today, probably most) code based on examples, not on documentation.  Nothing forces you to read the documentation.


Not writing documentation is certainly within your right, but this is a poor argument for not doing so.


I wasn't explaining why I don't write documentation (the reasons for that are lack of time&interest).  I'm not making a religion out of not writing documentation just because I don't like doing it.  Documentation *is* important, and I wasn't arguing anything else.
My point is that putting warnings in the documentation is not enough to prevent people from abusing the API, because many of them don't read it.


Certainly a main reason that people code from examples and not documentation is when documentation is poor.


I think it's one of the reasons, but I personally believe that coding by examples is better than coding by documentation (provided you have good examples).  Again, it doesn't come to say that documentation isn't important - it is important to have a reference, and some people do prefer coding that way.

Zeev

Thread (65 messages)

« previous php.dev (#65610) next »