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
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
