fixing the documentation problem
| From: | Greg Beaver | Date: | Tue, 21 Nov 2006 00:13:51 +0000 |
| Subject: | fixing the documentation problem | ||
| Groups: | php.pear.dev | ||
| Request: | Send a blank email to pear-dev+get-44974@lists.php.net to get a copy of this message | ||
Hi,
I know this isn't going to the pear-doc list, but I am addressing this
to PEAR developers who are not already involved in documentation.
I would like to encourage each of you to take one of the packages you
see at http://pear.cweiske.de/coverage/simple.html
that is highlighted
in red, and create a basic documentation page.
As an example, I just committed documentation for Auth_RADIUS, a package
I have never used and don't know anything about. Through google,
looking at source code, and reading a few things, I was able to find
enough information to direct users to answer a few key questions:
1) what is it?
2) how do I install it?
3) how do I use it?
For #3, I pasted the examples from the most recent release.
source for the docbook is in cvs in
peardoc/en/package/authentication.xml
peardoc/en/package/authentication/auth-radius.xml
peardoc/en/package/authentication/auth-radius/intro.xml
Doing this took me approximately 25 minutes.
Note that I also validated on windows using cygwin build instructions
(google "peardoc on windows"), and used "autoconf;./configure;make test"
to make sure it was all good stuff.
Please use this as a template to create your docs. If we each take 1
package that we don't maintain, and do this, it could kill the
undocumented packages issue on a basic level. Adding user comments will
also help, but that is for later.
Thanks,
Greg