Re: Re: Random Thoughts About Pear-Doc
| From: | Paul M Jones | Date: | Sat, 17 Apr 2004 22:05:39 +0000 |
| Subject: | Re: Re: Random Thoughts About Pear-Doc | ||
| References: | 1 2 3 | Groups: | php.pear.doc |
| Request: | Send a blank email to pear-doc+get-3608@lists.php.net to get a copy of this message | ||
On Apr 17, 2004, at 4:18 PM, Pierre-Alain Joye wrote:
See what, where? Links, man, links! :-) ("If Paul can't be bothered to look it up himself, then I'm certainly not going to do it for him," right? ;-)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.
I think you do and you don't know it. ;-) For example, when you say...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".They would be easy to miss. Let me point you to a recent one; Alexey asked, in the "Lack of docs reality check" thread:
And Jon Parise and I responded saying basically, yes, we would have put docs on PEAR-DOC if it wasn't for the current system. Here's the link to that thread:To those who feel that PEAR lacks docs because of DocBook format: have you *ever* seen a developer posting a message along the lines of "I *wrote* these cool docs, available here, but am unable to convert them to this horrible DocBook"? Clarification: it is quite different from "we *will* write docs, honest, if it wasn't for DocBook".
http://marc.theaimsgroup.com/?t=108184789400002&r=1&w=2So there are at least two people who have said what you say nobody has said. ;-) Here's the thing: you won't see too many people join up and then say "this sucks I'm leaving". They **do not join in the first place** because they can see what a heavy task it is to write in the current system. You'll never see all the people who would like to help because the system itself bars them from easily (!) doing so. The self-select themselves out of the process before we can see them.
Yes, "enough time and motivation" indeed. In other words, "if the doc-contributor can't take the time to learn the system, we don't want his help!" (Quoting myself there.) This is why I say you agree with me, at least partially, even though you don't think you do. We both think that it takes a certain level of "time and motivation" to work on docs through the current system. You think the level of "time and motivation" required is at the right level, and are arguing for the status quo; I say the level is far too high, and argue for changing the status quo.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...Perhaps the longer part probably is to write, rather than set up. But to write, and be accepted, one **must** set up the tools. That front-end barrier is too high. We want writers, not setter-uppers. Let them concentrate on writing as much as possible, and on tools as little as possible. Those French translators you talked about; if the system were easier to use, would they have had to contact you at all? Instead, they could have gotten to work **without** any hand-holding (or much less hand-holding) under a simpler system. Which I am working on proposing. ;-) -- Paul M. Jones pmjones@ciaweb.net Savant: the simple alternative to Smarty. http://phpsavant.com/