Re: Random Thoughts About Pear-Doc
| From: | Paul M Jones | Date: | Fri, 16 Apr 2004 16:28:24 +0000 |
| Subject: | Re: Random Thoughts About Pear-Doc | ||
| References: | 1 2 3 4 5 6 7 8 | Groups: | php.pear.doc |
| Request: | Send a blank email to pear-doc+get-3548@lists.php.net to get a copy of this message | ||
On Apr 16, 2004, at 11:14 AM, David Costa wrote:
If/when then time comes, I'll be asking for a role in the actual coding. Probably won't be up to me to "just do it" -- PEAR-Group needs will control.I think the doc system must become more like a web-based application, not a CVS repository that must be compiled from time to time -- perhaps a wiki-like system, but a wiki (proper) is not the only option, and may not even be a good option after reviewing available choices. But a web-based app it must be.I would have no problem with that if the majority agrees, the problem is who is going to do the "sit down and code" part :D
I like Martin's idea too. It is, for all practical purposes, what is serves as PEAR docs already (i.e., mostly API docs with very few examples/tutorials in relation -- although there are outstanding minority exceptions, such as DB, Auth, and others). However, it is the bare minimum necessary. API docs are great, don't get me wrong, but they serve mostly as reference, not as introduction/example/tutorial (which are what we need: prose narrative). API docs are just the inline comments, removed from their context (i.e., the source code itself), and as such are not sufficient by themselves. (Martin, I am sure, is on the same page with me there. :-)CONCLUSION: If we are to increase the amount and quality of PEAR documentation, I think we will need to have a documentation development system running **in parallel** to the current doc system on pearweb. Documentation might then be exported from it on a regular basis to the current system. This might at some point apply to the manual portions of pearweb itself. Once a parallel system is in place, it would be easier to transition from the one to the other, if such a transition is deemed necessary in the future.Personally I don't think that 2 system can easily co-exist. The export function is something I wouldn't know how to handle ;) but I am really open. I like Martin's idea of automated API documentation (not in Docbook) is really the best situation for now, IMHO.
We can do anything but we need to have people stepping in saying " I will do it" or better "here is my alternative " :DWorking on that now -- like I said: requirements determination, then technical review, then proposal. At least 30 days.
You are a good man, sir, and I will.I do not have a proposal for the parallel documentation system at this time, nor do I expect to have one in the next 30 days.okay let me know if I can do anything.
I am a big fan of open comments (and email notification of same!). They are in the requirements list even now. -- Paul M. Jones pmjones@ciaweb.net Savant: the simple alternative to Smarty. http://phpsavant.com/The above is speculative opinion. Any or all of it may become obsolete at any time. Thank you for your patience and time in reading this all the way through.One thing that might impress developers is comments. When some user will start saying "your package is good but heck I had to spend X hours to figure it out because is poorly documented" more developers might get down and do some more docs :D