Re: Random Thoughts About Pear-Doc

From: Date: Fri, 16 Apr 2004 16:14:14 +0000
Subject: Re: Random Thoughts About Pear-Doc
References: 1 2 3 4 5 6 7  Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3546@lists.php.net to get a copy of this message
On Apr 14, 2004, at 11:43 PM, Paul M Jones wrote:
Agreed with David that it is unlikely any complete off-the-shelf solution exists. I tend to assume that customizing any off-the-shelf solution will take at least as much effort as customizing or rebuilding the existing PEAR doc system. I also tend to assume that the existing doc system has enough inertia to it that replacing it entirely will just not be an option. There are good and valid assumptions underlying the current doc system. It has performed well for its purposes and may continue to do so. However, I think the doc system must become more dynamic, with a much shorter feedback loop, and significantly lower barriers to entry. This is the only way, in my opinion, to extend it into the future and encourage more documentation (of *any* kind, especially of the examples-and-tutorials kind). This does not mean DocBook must die, but it does mean there must be alternative methods to the current system and format, along with significantly more automation of initial and/or repetitive documentation tasks. 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 think that a wiki-like system would present several advantages, including live comments, live editing, iterative development of pages, simplified markup for most common semantics, and reduced need for client-side tools. Such a system would provide greater reward for less effort than the current doc system. I am really pro-wiki and pro-anything_else if is going to change the Docs situation
Installing a wiki-like system makes assumptions about the underlying structure of pearweb, at least for the manual and documentation portions. (To me, it appears the package browser and bug system are practically standalone applications as compared the rest of pearweb.) I do not believe the current structure of pearweb would support a wiki-like system. Thus, the underlying structure of pearweb would have to change radically to support anything other than what we currently have.
Then we have a problem :D
I do not think PEAR Group, PEAR Core, or PEAR Dev are ready, willing, or able to make radical changes to pearweb, either now or in the next 12 months. I do not believe there is enough interest, manpower, political will, or practical agreement to implement any major structural change to pearweb. This is not bad for now, and I do not think it spells immediate doom for pearweb, but I think it will become problematic later as there are more contributions and more calls for greater pearweb functionality. I believe PEAR Group foresees the structural failure of the current pearweb architecture even now, and I am sure they are working on the various issues. It is not my intent to flatly contradict their future plans for pearweb, such as they may be. 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 " :D
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.
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
Cheers David Costa

« previous php.pear.doc (#3546) next »