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

From: 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 &amp; 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

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