Re: Documenting Zend (was: zend_parse_parameters)

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