cvs: peardoc /en/guide/developers documentation.xml
| From: | Martin Jansen | Date: | Mon, 12 Apr 2004 10:03:50 +0000 |
| Subject: | cvs: peardoc /en/guide/developers documentation.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-3238@lists.php.net to get a copy of this message | ||
mj Mon Apr 12 06:03:50 2004 EDT
Modified files:
/peardoc/en/guide/developers documentation.xml
Log:
* Merging the documentation tips, which were previously available in
"Writing documentation in pratice", into the documentation chapter.
* Adding more information about DocBook
http://cvs.php.net/diff.php/peardoc/en/guide/developers/documentation.xml?r1=1.6&r2=1.7&ty=u
Index: peardoc/en/guide/developers/documentation.xml
diff -u peardoc/en/guide/developers/documentation.xml:1.6
peardoc/en/guide/developers/documentation.xml:1.7
--- peardoc/en/guide/developers/documentation.xml:1.6 Fri Apr 9 17:28:14 2004
+++ peardoc/en/guide/developers/documentation.xml Mon Apr 12 06:03:50 2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1" ?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
<!--
WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING
THIS DOCUMENT YET.
@@ -24,31 +24,40 @@
</para>
<sect1 id="developers.documentation.docbook">
- <title>Docbook XML</title>
+ <title>The DocBook XML format</title>
+ <titleabbrev>DocBook XML</titleabbrev>
<para>
- <ulink url="&url.docbook.xml;">Docbook</ulink> is an XML dialect
+ <ulink url="&url.docbook.xml;">DocBook</ulink> is an XML dialect
that is used by a wide range of projects to maintain their
- documentation. Examples for Docbook usage in OpenSource projects are
+ documentation. Examples for DocBook usage in OpenSource projects are
the documentations of <ulink url="&url.kde;">KDE</ulink> and
<ulink url="&url.php;">PHP</ulink>. PEAR has opted for using
- Docbook, because we believe that it provides a solid foundation for
+ DocBook, because we believe that it provides a solid foundation for
the technical documentation for PEAR packages.
</para>
<para>
- The trade-off for using Docbook is that it is relatively hard to
+ The trade-off for using DocBook is that it is relatively hard to
use. Testing documentation requires a number of tools to be
installed and one needs to learn a (not very complicated) XML
- dialect. Once one is familiar with how Docbook works, they will
- enjoy writing documentation with it though.
+ dialect. Once one is familiar with how DocBook works, they will
+ enjoy writing documentation with it though.
+ </para>
+ <para>
+ The book <ulink url="&url.docbook.book;"><emphasis>DocBook: The
+ Definitive Guide</emphasis></ulink>, written by Norman Walsh and
+ Leonard Muellner and published by <ulink
+ url="&url.oreilly;">O'Reilly & Associates, Inc.</ulink>, is
+ <ulink url="&url.docbook.book.read;">available online</ulink> and it
+ makes up a great resource for people interested in learning DocBook.
</para>
<sect2>
<title>Required software</title>
<para>
- Even if Docbook XML can (like any other XML file) be written using
+ Even if DocBook XML can (like any other XML file) be written using
a normal text editor, one needs to install some software on their
machine in order to test the validity of the documenting
efforts. A list of the required software and a installation
@@ -110,7 +119,7 @@
<para>
Instead of a long and boring description for writing documentation
- using Docbook, we would like to point you to a bunch of
+ using DocBook, we would like to point you to a bunch of
<quote>reference documentations</quote>, from which you should be
able to learn quickly:
@@ -164,8 +173,10 @@
<para>
In addition to the examples above, you will find much more
documenation examples by browsing the <filename>peardoc</filename>
- directory, which contains your local version of the CVS tree. You
- can also browse the CVS module using the <ulink
+ directory, which contains your local version of the CVS
+ tree. Especially the directory
+ <filename>peardoc/en/packages/</filename> should be of interest for
+ you. You can also browse the CVS module using the <ulink
url="&url.pear.cvs.peardoc;">web interface</ulink>.
</para>
</sect2>
@@ -175,7 +186,7 @@
<simpara>
We are well aware that we cannot cover all questions about writing
- Docbook documentation in this chapter. If you have more questions
+ DocBook documentation in this chapter. If you have more questions
or problems, do not hesitate to get in touch with the documentation
team at <ulink
url="mailto:&email.pear.doc;">&email.pear.doc;</ulink>.
@@ -183,6 +194,72 @@
</sect2>
</sect1>
+
+ <sect1 id="developers.documentation.tips">
+
+ <title>Tips for good documentation</title>
+ <titleabbrev>Documentation Tips</titleabbrev>
+
+ <para>
+ This section of the chapter does not deal with the specifics of
+ organizing documentation in the <literal>peardoc</literal> standard,
+ but instead with how to organize documentation logically.
+ </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 novice programmer can 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>
+ Provide examples! Start right away with simple examples that
+ shows the basic feature set -- they will show users how to
+ quickly start using the package. More complex examples will help
+ the users in understanding advanced ways of using the package.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If your package exposes complex interfaces or multiple constants
+ that can't be fully explained in one or two examples (which is
+ very likely), do not miss to explain them thoroughly in the
+ documentation. 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>
+ 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.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect1>
</chapter>
<!-- Keep this comment at the end of the file