cvs: peardoc /en/guide/developers contributing.xml

From: Date: Mon, 12 Apr 2004 10:04:23 +0000
Subject: cvs: peardoc /en/guide/developers contributing.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3239@lists.php.net to get a copy of this message
mj Mon Apr 12 06:04:23 2004 EDT Modified files: /peardoc/en/guide/developers contributing.xml Log: * The tips have been merged into the new documentation chapter. http://cvs.php.net/diff.php/peardoc/en/guide/developers/contributing.xml?r1=1.18&r2=1.19&ty=u Index: peardoc/en/guide/developers/contributing.xml diff -u peardoc/en/guide/developers/contributing.xml:1.18 peardoc/en/guide/developers/contributing.xml:1.19 --- peardoc/en/guide/developers/contributing.xml:1.18 Sun Mar 14 14:33:35 2004 +++ peardoc/en/guide/developers/contributing.xml Mon Apr 12 06:04:23 2004 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1" ?> -<!-- $Revision: 1.18 $ --> +<!-- $Revision: 1.19 $ --> <!-- WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING THIS DOCUMENT YET. @@ -373,70 +373,12 @@ <sect1 id="developers.contributing.docs"> <title>How to document code in practice</title> <titleabbrev>How to document</titleabbrev> - <para> - This section of the manual does not deal with the specifics of organizing - documentation in the peardoc standard, but instead with how to organize - documentation logically. To learn about authoring documentation files in - peardoc format, please look in PHP's CVS - <ulink url="&url.php.cvs.peardoc.authoring;">here</ulink>. - </para> - <para> - Follow a few basic rules when documenting a package, and you will have - good documentation. - </para> - <para> - <orderedlist> - <listitem> - <para> - First, every package solves a problem. What is this problem? Try to - figure out what assumptions your end-users might not have about the - problem (they may not realize that this is a problem that needs solving). - For instance, a template package solves the problem of both separating - design from code, and separating business logic from display logic. - If possible, explain the problem in terms that even a beginning programmer - could understand. - </para> - </listitem> - <listitem> - <para> - Next, how does the package uniquely solve the problem? This is something that most - documentation lacks. For example, there are many template engines. All of them - solve the same problem, but none of them do it in the same way. A - block-based template engine does not have any logic at all, whereas - a template like Smarty defines a whole new template language. Some - template engines compile their templates, others don't. What is unique - about your package? Can someone who has never seen the code get a good - idea of how it solves the problem? - </para> - </listitem> - <listitem> - <para> - Last, every publicly accessible aspect of the package must be - thoroughly documented. If your package is a re-usable class, document - every method that users should expect to use. If your package has - constants that are publicly accessible, document their meaning and where - they should be used. Document any interfaces that users must use, such - as a database DSN, command-line arguments for applications, configuration - file contents, or any other non-code element. - </para> - </listitem> - <listitem> - <para> - Include at least 2 code examples: one simple and one complex. This is - obvious, but PEAR packages are designed to be used: show your users how - to use them! :) - </para> - </listitem> - <listitem> - <para> - Last, proofread your documentation. If possible, have someone else who is - not as familiar with your project take a look at the documentation. They - will catch assumptions that you have missed. This is probably the most - important step of all. - </para> - </listitem> - </orderedlist> - </para> + + + <simpara> + Writing documentation is covered in a <link + linkend="developers.documentation">dedicated section</link>. + </simpara> </sect1> </chapter>

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