Re: Re: Random Thoughts About Pear-Doc

From: Date: Sat, 17 Apr 2004 21:18:43 +0000
Subject: Re: Re: Random Thoughts About Pear-Doc
References: 1 2  Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3607@lists.php.net to get a copy of this message
On Sat, 17 Apr 2004 09:41:30 -0500 pmjones@ciaweb.net (Paul M Jones) wrote: > 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). See LiveUser, tests request on peardoc, cooperations. > And then learn CVS, and request an account, and test the > connection, and then upload the compiled DocBook. That will not change, unless the write post his work on peardoc. Then someone around will commit it. > 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. See LiveDocs. And _once_, read Alexander Merz post, multiple references to LiveDocs (explanation, goals, ...). And finnally the peardoc archives. People in peardoc (I mean those _who_ write docs and not only talk about writing) are always open to convert a basic format (text or whatever) to docbook if there is at least something to convert. > 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. Checking the archives, I do not agree with you. Checking again the archives, I missed the posts where someone says: "good bye, I do not want to write peardoc due to overkilled formats". Some months ago, french translators contacted me about the french translations, about the difficulty to work with our current format, they are now some of the most active writers. Do not get me wrong, that does not mean we cannot work on tools to help the process, but that means it's not that difficult. Enough pear fellows got some working docbook tools and should help to valid, until livedocs is up. > 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 ;-). I really doubt that will help that much. People with enough time and motivation will join the effort, soon or later. Maybe adding a note to the contributions page saying that they can send us documents in text or html format (basic html) is always helpfull. We can then convert the docs to docbook. I'm still convinced that the longer part is not to setup some tools but to write the docs... pierre

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