Re: Documentation..

On Nov 15, 2004, at 5:56 PM, Daniel Convissor wrote:

On Mon, Nov 15, 2004 at 03:36:14PM -0600, Paul M Jones wrote:

Hinting that the lack of docs is Thomas' fault somehow,

I did no such thing. If you interpreted it as such, then you have a different sense of humor than I do.

It won't be the first time I've heard that. :-) But let us review my point of contention. You said:

I agree. And since this is an open source, volunteer based project, it's up to you to make it happen. So, Thomas, you want to see more documentation? And you want us to demand it?

    THOMAS!  GET WRITING!  NOW!

I'm teasing you with my tone, of course, but not with the point. Things only happen because people do them. So, please do it.

That does seem like assignment of fault to me (or of responsibility, anyway, or delegation of a nuisance task) notwithstanding my failure to find your humor. If someone points out a bug in code, our first response would not be "you found it, you fix it!" but "the author should commit that fix" (and QA should if he does not). The standard reaction seems so wildly different with respect to calls for documentation; blame somehow goes to the person asking for documents, because PEAR is "open source" and authors are "too busy" (or any of a host of other excuses). I suppose could go so far as to call "lack of documentation" a type of usability bug. It's a funny kind of bug, because its effect is felt less as the novice user pushes back against it (i.e., digging into code line-by-line, trial-and-error, and so on to become one of the initiated) but always pops up again for new users of exactly the same code. Certainly the bug is never seen by the original author; but then, he isn't a novice user. As a quick sanity check, how many people here have written from-scratch documentation for an open-source project for which he/she did not write code? How many times has anyone here taken the time to learn a new package, then turned around and started new documentation for it? As for me, never that I can think of (although I do make comments on existing documentation). I would warrant that very few, if any, of us have (David Costa is one example of such an angel). There's just not much reward in it. And really, Thomas has a very valid set of points. He said:

It will make it lot easier to quickly get an overwiew of a given package.. and as the number of packages is growing string it will be very cumbersome to read API's for all the packeges to get the rigth one or just to find out if it actually exists..

What is wrong with these statements (aside from English nazi-ing)? Nothing. He is exactly right. Thomas, I too bemoan the lack of documentation in PEAR. I don't think it's my responsibility to document someone else's project, and I don't think it's yours -- I think the code author needs to do it. I believe the author who presents only code and no docs is at best only half finished. -- Paul M. Jones Savant: the simple alternative to Smarty for PHP. http://phpsavant.com/ DB_Table: build RDBMS tables and XHTML forms in one PHP class. http://wiki.ciaweb.net/yawiki/index.php?area=DB_Table Yawiki: your collaborative online documentation system. http://yawiki.com/ Yawp: a single-file foundation for PHP applications. http://phpyawp.com/