On Mon, 10 Sep 2001, Zeev Suraski wrote:
> 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.
>
hrmm, imho, good documentation has at its core, good examples,
it is extremely important to reinforce concepts in the text with
real-life examples.
-Sterling
--
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]
