------------------------------------------------------------ revno: 733 committer: Jason P. Pickering <jason.p.picker...@gmail.com> branch nick: dhis2 timestamp: Wed 2009-09-16 08:41:00 +0200 message: Added guide for how to produce DHIS2 documentation in DocBook format added: docs/src/docbkx/dhis2_documentation_guide.xml
-- lp:dhis2 https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk Your team DHIS 2 developers is subscribed to branch lp:dhis2. To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk/+edit-subscription.
=== added file 'docs/src/docbkx/dhis2_documentation_guide.xml' --- docs/src/docbkx/dhis2_documentation_guide.xml 1970-01-01 00:00:00 +0000 +++ docs/src/docbkx/dhis2_documentation_guide.xml 2009-09-16 06:41:00 +0000 @@ -0,0 +1,104 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";> +<article> + <articleinfo> + <title>DHIS 2 Documentation Guide</title> + + <author> + <firstname>Jason</firstname> + + <surname>Pickering</surname> + + <affiliation> + <orgname></orgname> + </affiliation> + </author> + + <pubdate>14/09/09</pubdate> + + <keywordset> + <keyword>DHIS2</keyword> + + <keyword>documentation</keyword> + + <keyword>DocBook</keyword> + </keywordset> + </articleinfo> + + <section> + <title>DHIS 2 Documentation System Overview</title> + + <para remap="">DHIS 2 is a web-based information management system under + very active development. Currently, there are a large number of + disconnected pockets of documentation across in various formats (e.g. + MediaWiki, Word documents, Confluence). There is a need to consolidate the + documentation process and bring it more inline with the distributed nature + of the development of the application itself. It has been suggested + therefore to move the current documentation to the DocBook platform. This + article will not discuss the relative merits of the DocBook platform, but + rather will serve as a brief guide to its use by DHIS 2 implementers, + users and developers. Readers are encouraged to make their own decision + about whether to use DocBook or not for documentation purposes.</para> + </section> + + <section> + <title>Getting started</title> + + <para>One of the main advantages of DocBook is that there is complete + seperation between the content and presentation. DocBook is a pure XML + format, and is well documented. It is beleived that only a very small + subset of its features will be required in order to acheive much higher + quality documentation for DHIS. There are some 400 seperate mark-up + elements that cater to almost any level of technical documentation needs, + but in reality, only a few dozen of these element will probably need to be + employed to achieve high-quality documentation for DHIS 2, both for + printed as well as online formats such as HTML or integrated help systems + with the application itself. Therefore, there are wide range of + possibilities in terms of which editor can be used for the creation of + DocBook files. A fairly complete list of possibilities is located <ulink + url="http://wiki.docbook.org/topic/DocBookAuthoringTools";>here</ulink>. + <ulink url="http://www.xmlmind.com/xmleditor/persoedition.html?";>XMLmind + XML Editor Personal Edition</ulink> is a good balance between + functionality and simplicity. </para> + + <para>One of the key concepts to keep in mind when authoring documentation + in DocBook, or other presentation neutral formats, is that the <emphasis + role="bold">content </emphasis>of the document should be considered in the + first instance. The <emphasis role="bold">presentation </emphasis>of the + document will take place in a seperate step, where it will be rendered + into different formats, such as HTML and PDF. It is therefore important + that the document is will organized, and strctured, with appropriate + DocBook tags and structural elements being considered. </para> + + <para>It is good practice to break your document in to various sections + using the "sect", or section element. Section elements can also be nested + within each other, such as "Section 1" and "Section 2". This concept is + essentially the same as Microsoft Word or other word processing programs. + DocBook will automatically take care of numbering the sections for you + when the document is produced. Two other important elements are the + "itemizedlist" and "numberedlist". These are quite similar, but an + itemized list corresponds to a bulleted list, which a numbered list will + be rendered with each element being numbered sequentially. Other key + elements are "screenshot" and "table" which should be self-explanatory. + </para> + </section> + + <section> + <title>Producing DHIS2 documentation</title> + + <para>Currently, the documentation system is part of the source code + housed at <ulink url="???">Launchpad</ulink>. In order to start adding or + editing the documentation, you should first perform a checkout of the + sourcecode. Edit your DocBook document and place it in the + <filename>/dhis2/docs/src/docbkx</filename> directory. Place any image + files that may be linked to your document in the + <filename>/dhis2/docs/src/docbkx/images/</filename> folder. Be sure to + test if you document is actually valid by running <command>mvn + docbkx:generate-html</command>from the <filename>/dhis2/docs</filename> + main documentation directory. This command will generate an HTML document + from your DocBook source images and place them in the + <filename>/dhis2/docs/target/site/html</filename> directory. You can then + commit these documentation changes to the main source code tree. </para> + </section> +</article>
_______________________________________________ Mailing list: https://launchpad.net/~dhis2-devs Post to : dhis2-devs@lists.launchpad.net Unsubscribe : https://launchpad.net/~dhis2-devs More help : https://help.launchpad.net/ListHelp
