Re: Publishing API documentation for each release

Martin Jansen wrote:

* I haven't generated documentation for all PEAR packages yet, so I don't know if my phpDocumentor templates work well with all of them.

This we will figure out one by one.

* I don't know if actually a majority of you agrees with me on the idea that publishing API documentation for all packages is a good thing and that this documentation should be detached from the PEAR manual. The reason for detaching the API docs is by the way performance: Right now it takes > 40 minutes to build the HTML version of the manual on our build box. Adding API documentation for each of our 209 packages will cause the build time to grow nearly exponentially. Another reason is the ability to provide the API documentation in form of man pages or tar archives in the future, which isn't feasible without detaching.

Yup they should be detached.

* What will happen to the existing package documentation that is part of the PEAR manual? (E.g. the docs for DB, XML_Beautifier and XML_RSS.) I suggest we keep it and also give people the chance to add more documentation there: Everything that specifically aims at end-users (like tutorials, longish examples etc.) will be part of the manual, while the pure API documentation will be available in form of independent collections.

+1, however the manual should also include the API docs They should stay as is. The online docs will be more complete I would assume. Also they will include more little hints like feature xyz was add in version abc and method foo only available since release bar, whereas the APi docs for a specific release will just document that single release obviously. Furthermore those API docs will never be translated.

* What should we do about stuff like the reST-based user guides that Jon is providing for Log and Net_SMTP? Since reST is actually a very cool format, we should find a way to integrate them somewhere.

I guess we actually have high hopes for reST becoming our ultimate doc format in the long run, since its just all around easier to create and test. regards, Lukas Smith smith@backendmedia.com _______________________________ BackendMedia www.backendmedia.com berlin@backendmedia.com Linn Zwoch Smith GbR Pariser Str. 44 D-10707 Berlin Tel +49 30 83 22 50 00 Fax +49 30 83 22 50 07