Re: Re: Random Thoughts About Pear-Doc

From: Date: Sat, 17 Apr 2004 14:41:30 +0000
Subject: Re: Re: Random Thoughts About Pear-Doc
References: 1  Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3605@lists.php.net to get a copy of this message
On Apr 17, 2004, at 9:15 AM, Jesus M. Castagnetto wrote:
I usually use vi/vim (with some simple scripts I wrote for the latter), but then again I am an old Unix fart :-) Check out pollo (pollo.sf.net). I've used it with good results to write XML Schema documents. Oftentimes I also use tidy (tidy.sf.net) to check that my docs are well-formed, and when things are a big more complex, I use xmllint. Also, several other Open Source editors support an XML mode for editing (e.g. emacs).
Look back over your paragraphs and see them as a doc-n00b. Think about how much time it took you to learn not only XML, but the specifics and pitfalls of DocBook, and then the time it took to find, download, set-up, and learn how to work with the programs. And then the time to organize your ideas and mark up the documentation, and then the time and effort to compile, test, re-work, and re-compile the results (probably multiple times). And then learn CVS, and request an account, and test the connection, and then upload the compiled DocBook. And then wait until Sunday for the build to complete and see that you made a mistake on one or more pages: re-work, re-compile, re-test, wait until Sunday, repeat. The task overall is quite daunting. Some of the elements are necessary no matter what (organize, request account) but some might be removed under another doc system. The standard response of "Well, if the doc-contributor can't take the time to learn the system, we don't want his help!" accurately describes the status quo: they **don't** want to learn the system, because the effort-to-reward ratio is too poor, and we don't get more docs. There you have PEAR-DOC right now. This comes back to one of my points from the source post, paraphrased and extended. //Reduce// the need to acquire, configure, and learn the use of client-side tools. //Simplify// the markup where we can. //Automate// as much as possible. //Shorten// the feedback loop (to "immediate" if we can). Some kind of tool or system is always going to be be necessary; that cannot be eliminated entirely. But if we lower the barriers to a more reasonable level, I believe the quantity of user-contributed documentation will increase (quality is another matter, although quantity has a quality all its own ;-). (Yes, I am working on a solution proposal; this is not aimless whining. ;-) -- Paul M. Jones pmjones@ciaweb.net Savant: the simple alternative to Smarty. http://phpsavant.com/

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