dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 733
committer: Jason P. Pickering <jason.p.pickering@xxxxxxxxx>
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>