dhis2-devs team mailing list archive

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

Johan, an iPhone is pretty cool, but not if you are using it with Emacs to
edit a DHIS manual using DocBook. :) Good thing you were just reading up on
it!

The intrinsic problem with formats such as DockuWiki is that they are pretty
much a one way street. It is an easy format to use, but not entirely easy to
transform into something else. Pure XML formats such as DocBook separate
entirely the content away from the presentation. Want Word? No problem. How
about PDF? Can do. How about an integrated help system with the application?
Should not be an issue as you have pure XML to work with. DocBook solves
that problem, as the content and presentation are completely separate and
dependent only on XML style sheets, of which there are many already
developed.

I am looking at it from the perspective of having a documentation system
that is completely portable to essentially any format, and not necessarily a
browser based format. People often want an actual printed manual and
especially here where I am, it needs to work offline as well as online.What
works on a wiki, may not necessarily work on A4.  For instance, what if I
want to get this (
http://www.openhealthconsortium.org/wiki/doku.php?id=organisation_units)
inside of a user manual to view as PDF? Well, I guess I can print it out
maybe, but it won't be so easy to do it for the entire Wiki. However, if the
original source of the documentation is DocBook (i.e. XML) it is no problem
to render HTML or MediaWiki format, via the plugin that Knut mentions.


I think it would be good to get the feedback of the technical writer before
a final decision is made on way or the other. I am not an expert in either
DocBook or technical documentation (nor a particularly good salesman), but I
have been impressed by how easy it has been to learn, and the amount of
possibilities it opens if documents are authored with content in mind first,
and presentation second, much as application development separates business
logic away from the presentation itself.

Anyway, my two extra cents.



On Thu, Sep 10, 2009 at 8:18 PM, <johansa@xxxxxxxxxx> wrote:

> Well, I was caught off guard yesterday and called a "nerd" for the first
> time in my life as a collague saw I was reading about docbook on my
> cellphone during a dinner party...
>
> As I think Ola mentioned on this list, we have a (doku)wiki up and running
> here
> http://www.openhealthconsortium.org/wiki/doku.php?id=dhis_2_documentation
>
> We are in the process of making a ToC, and HMN is hiring a technical
> writer to contribute. Of course he doesn't know DHIS as well as the
> developers (but that is also an asset sometimes), but he has written large
> manuals before and should be able to help us with style, language etc. The
> idea is that each page can be translated to other languages, so as soon as
> we get something down in english, the same pages can be translated by
> users and developers into their own language. There is also a wiki2pdf
> function, but I haven't tested that yet. The content of the wiki can of
> course be kept locally (such as on the DHIS-on-a-stick Ola and Knut has
> worked on), and updated when online.
>
> Is there a need for another platform? I think the most important is to get
> something substantial quite soon. I have no idea if docbook is compatible
> with the wiki, there might be some export functionality?
> Johan
>
> > Helvete.  Sorry. Was meant to go the entire list.
> >
> > I will  give a try with this the GIS document, and then we will see if
> > DocBook catches on for the documentation, which I will be willing to help
> > with as well, but this is obviously a bit more work. :)
> >
> > Regards,
> >
> >
> >
> > On Thu, Sep 10, 2009 at 6:20 PM, Jo Størset <storset@xxxxxxxxx> wrote:
> >
> >> (I guess this mail just reached me?)
> >>
> >> Den 10. sep. 2009 kl. 17.25 skrev Jason Pickering:
> >>
> >> Bob- I tried with OpenOffice, but was did not succeed. It seems to be
> >> for
> >> older versions and I could not get it to work with my version (3.1 on
> >> Windows).
> >>
> >> Jo, I completely agree with you, to a certain point. It will not
> >> necessarily speed up the process necessarily, but it will make it more
> >> sustainable and flexible. It is easy enough to go from DocBook into
> >> HTML,
> >> and not too difficult to go the other way. I am just thinking in the
> >> long
> >> term. In addition to documentation, we need to think about training
> >> materials, user guides and so forth. I am not sure that the Wiki
> >> approach
> >> necessarily lends itself to developing these types of materials. I think
> >> the
> >> Wiki is a great tool for collaboration. Actually, I think in many places
> >> (Zambia for instance where I am) having access and the ability to
> >> check-out
> >> documentation, edit it, and check it back in is actually preferable to
> >> having to be connected and edit it on a Wiki. Internet access is
> >> incredibly
> >> expensive, slow and difficult to access here. One of the reasons why I
> >> would
> >> prefer the version control system (in addition to it being version
> >> controlled) is that i only need to download what is new, like the code.
> >>
> >> I agree with your point that it raises the bar a bit in terms of having
> >> to
> >> get a version control client installed, and learn the structure of
> >> DocBook,
> >> but I also feel that as much effort that given that so much effort has
> >> and
> >> is being put into the coding of the application, the documentation of it
> >> should be just as rigorous. It may be more difficult, but it certainly
> >> is
> >> the better choice in my mind.  DocBook seems to work great for other
> >> OpenSource projects, but I am not going to spend any more effort
> >> beginning
> >> to develop the docs, if it is not going to be sustainable.
> >>
> >> Knut, Ola, anyone else..thoughts?
> >>
> >>
> >> I guess I could have made my position clearer: go for it! Since you are
> >> willing to contribute to the documentation, we should tailor everything
> >> to
> >> your needs. Let us deal with the other stuff later, when we have to
> >> worry
> >> about maintaining great documentation :)
> >>
> >> Jo
> >>
> > _______________________________________________
> > Mailing list: https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
> > Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
> > More help   : https://help.launchpad.net/ListHelp
> >
>
>
>