Re: Re: Livedocs
| From: | Paul M Jones | Date: | Mon, 23 Feb 2004 17:52:37 +0000 |
| Subject: | Re: Re: Livedocs | ||
| References: | 1 2 3 4 5 6 | Groups: | php.pear.dev |
| Request: | Send a blank email to pear-dev+get-25823@lists.php.net to get a copy of this message | ||
On Feb 23, 2004, at 11:40 AM, Arnaud Limbourg wrote:
Correct. Inline comments help you understand what's going on in the code, but they are *comments*, not "documentation." Docs are a different thing altogether, although comments can help you get started on docs.I didn't mean it like that. More like Javadoc or phpdoc type comments right in the source code files. Having separate documentation files in the project tree isn't much better than having them in a separate site.Yes, but this kind of documentation is not enough. This topic has been discussed before but what comes out is that phpdoc is nice for developpers. End-users need other type of docs, tutorials, quick start, younameit.
A developer should write some doc yes but external people like users have another view and can make very good documentation (that's why there are some technical writers out there :)And they can point out "weirdness" or unexpected behavior, add examples, posit theories for enhancement, etc. And if you have more than one developer on a project (many PEAR packages do) you can back-and-forth collaboratively on a Wiki in real-time, fixing errors as they come up. -- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/