cvs: peardoc /en/guide/developers contributing.xml
| From: | Martin Jansen | 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>