dhis2-devs team mailing list archive

[Jason Pickering <jason.p.pickering@xxxxxxxxx>]

Hi Everyone,

I have been speaking with Jan and Old a bit about documentation and before I
start committing anything, or making too many changes, I would like to get
some feedback from everyone.

Let me be quite honest. I find the documentation of DHIS2 to be quite
appalling. It is scattered between different Wiki sites, Launchpad, mailing
lists, and various documents here and there. We need to do better.

Jan has started a document on the GIS portion of DHIS2 and I would like to
suggest that we standardize all documentation by using the DocBook
format.Visit  www.*docbook*.org for more info. I will not repeat the various
advantages of using this format over others, other than to say it is very
common, it is structured, and is supported by a large number of editors and
can be transformed into essentially any format . Since DocBook is pure XML
it is much more suited to the sort of distributed development environment we
are working in, as opposed to say proprietary, binary word documents or
other formats.

Any reactions here? I have started a bit of work on the conversion of the
GIS manual to DocBook format, but wanted to get feedback from the community
before I proceeded much further. Of course, documentation in a structure
format like XML will be a bit more painful, but there are several tools out
there (many of them OpenSource) that provide good editors for the format. Of
course the ability to transform this XML info many different formats, such
as HTML, Word, PDF, JavaHelp files (the list is very long) is a big
advantage in my mind.

What does everyone think?

Best regards,
Jason