Re: Documentation..
| From: | Paul M Jones | Date: | Mon, 15 Nov 2004 21:36:14 +0000 |
| Subject: | Re: Documentation.. | ||
| References: | 1 2 | Groups: | php.pear.qa |
| Request: | Send a blank email to pear-qa+get-1941@lists.php.net to get a copy of this message | ||
On Nov 15, 2004, at 2:05 PM, Daniel Convissor wrote:
Hi Thomas: On Mon, Nov 15, 2004 at 03:54:20PM +0100, Thomas Husfeldt wrote:He won't, because has no reason to; Thomas has nothing invested in the success or failure of the package, he just wants to solve a problem. He'll go on to another project that **has** documentation, or will write his own new code, or will spend more time learning the package and then not-write any docs for it. Hinting that the lack of docs is Thomas' fault somehow, and that it is his responsibility to document someone else's package, is counterproductive and certainly not a welcoming or friendly attitude. Documentation is primarily the responsibility of the code author, nobody else. The original code author knows more about it than anyone. If the docs do not exist, it is not the fault of the end user; it is the fault of the code author, who must either write them himself or commission someone to write them on his behalf. Users who don't know your package won't write your docs for you. http://paul-m-jones.com/blog/index.php?p=14 http://paul-m-jones.com/blog/index.php?p=15 http://paul-m-jones.com/blog/index.php?p=16 (Thomas, if you want to prove me wrong in this case, I will be happy to be wrong -- but I would argue the point still stands for the vast majority of cases. :-) -- 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/I would really like to have this improved.... snip ...In other words I would like you to please demand or strongly request a minimal end-user -- like a "hello world" example for the various pear packages..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.