Random Thoughts About Pear-Doc

From: Date: Wed, 14 Apr 2004 21:43:59 +0000
Subject: Random Thoughts About Pear-Doc
References: 1 2 3 4 5 6  Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3465@lists.php.net to get a copy of this message
Hi, David,
Right, the list is rich enough. So I bet you will have and hard time finding a perfect ready made solution. I suspect you have something in mind already, is it true ? If so share :)
OK, but remember, you asked for it. ;-) These are my thoughts, in some sort of imperfect order. They are in many ways heretical and I expect there to be strong opposition to them. I am not advocating that we do *any* of the following; in fact, I strongly suggest a slow and measured course. First, do nothing; then, think about it; then, do nothing. ;-) I do not have a solid proposal based on any of the following points. I want to get doc-system requirements completed before evaluating anything. Having said that, I still have a very broad and chaotic idea of what might be necessary. I have no emotional commitment to any of the following points, and will rapidly change my mind if any of them prove untrue. Here we go. ---- 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 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. 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. 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. 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. 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. -- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/

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