RE: [PEAR-DEV] Documentation

> From: Daniel Khan [mailto:dk@webcluster.at] > Sent: Saturday, April 26, 2003 10:59 AM > Mirco 'meebey'Bauer wrote: > > [..] > > I agree with this, I got the same problem a while ago, my > > solution was simlpy not to use PEAR packages without any > documentation... > > I know its bad, but I tried already to show some PEAR developers the > > need of documentation. On the discussion it ended up with "you know I > > spent alot time for PEAR coding, and I don't have time for doing > > documentation too..." > > > > <IMO> > > when _I_ use libraries from other developers, I don't want to see their > > code. I know mine thats how it should be.... searching in others code > > for how things work is pain, because you usually don't know the design > > of the library (gets worse when the library is splitted in different > > classes and files). > > Also I hear often, "I got examples, thats documentation...", examples > > are only a part of documentation, they don't explain much about the > > library itself... also having for every situation an example is not > > possible for big libraries... > > </IMO> > > ACK - BUT what can be done to solve the problem? > There is no realistic way to force one to write a propper docu. > And to demand a full docu on package proposal isn't the right way either I > think. > What shall be done with existing, important, packages without docu? I think we are on the right track with a bunch of things we are doing or have started. 1) auto generate the API docs with the tool Christian started 2) stuff like phpDocumentator and hopefully an OO template to make docbook easier 3) possibly PFC's that require documentation generally we need to spend some more time with documentation of the documentation effort I guess :-) Also tutorials would be helpful and maybe even a more formal documentation team (actually we sort of have that with pear-doc@). I think a lot of PEAR users would like to give back to the community and are willing to help there if we have a team of people who they can turn to and which can point them to tutorials etc and answer questions the documentation will grow I am sure. Regards, Lukas