[prev in list] [next in list] [prev in thread] [next in thread] 

List:       pear-doc
Subject:    [PEAR-DOC] cvs: peardoc /en/chapters standards.xml  /en/guide/developers contributing.xml
From:       "Greg Beaver" <cellog () php ! net>
Date:       2003-08-30 6:59:32
[Download RAW message or body]

cellog		Sat Aug 30 02:59:32 2003 EDT

  Modified files:              
    /peardoc/en/chapters	standards.xml 
    /peardoc/en/guide/developers	contributing.xml 
  Log:
  More doc fixes, add in section on documenting to contributing
  
Index: peardoc/en/chapters/standards.xml
diff -u peardoc/en/chapters/standards.xml:1.6 peardoc/en/chapters/standards.xml:1.7
--- peardoc/en/chapters/standards.xml:1.6	Sat Aug 30 02:15:14 2003
+++ peardoc/en/chapters/standards.xml	Sat Aug 30 02:59:31 2003
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1" ?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
  <chapter id="standards">
   <title>Coding Standards</title>
   <note>
@@ -154,7 +154,7 @@
    <para>
     Inline documentation for classes should follow the PHPDoc
     convention, similar to Javadoc. More information about PHPDoc can
-    be found here: <ulink url="&url.phpdoc;">&url.phpdoc;</ulink>
+    be found here: <ulink url="&url.phpdocumentor;">&url.phpdocumentor;</ulink>
    </para>
    <para>
     Non-documentation comments are strongly encouraged. A general rule of
Index: peardoc/en/guide/developers/contributing.xml
diff -u peardoc/en/guide/developers/contributing.xml:1.9 \
                peardoc/en/guide/developers/contributing.xml:1.10
--- peardoc/en/guide/developers/contributing.xml:1.9	Sat Aug 30 02:15:16 2003
+++ peardoc/en/guide/developers/contributing.xml	Sat Aug 30 02:59:32 2003
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1" ?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!--
      WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING
      THIS DOCUMENT YET.
@@ -318,6 +318,74 @@
        and upload the tgz file that has been created previously there.
        This will start the automated release process, which will roll
        out version 1.0 of the package Money_Fast.
+      </para>
+     </listitem>
+    </orderedlist>
+   </para>
+  </sect1>
+  <sect1 id="developers.contributing.howto">
+   <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 
+    <link linkend="&url.php.cvs.peardoc.authoring;">here</link>.
+   </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 most
+       documentation lacks.  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>

-- 
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php


[prev in list] [next in list] [prev in thread] [next in thread]