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.
One suggestion. Make sure there are free open source translation tools (OS independent) for DocBook, because DHIS docs should be translated into many other languages too.
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’s wrong with vi? No seriously, cross-platform and multilingual issues should not be a problem. There are many possibilities, including Eclipse for the devs.
One suggestion. Make sure there are free open source translation tools (OS independent) for DocBook, because DHIS docs should be translated into many other languages too.
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’s wrong with vi? No seriously, cross-platform and multilingual issues should not be a problem. There are many possibilities, including Eclipse for the devs.
One suggestion. Make sure there are free open source translation tools (OS independent) for DocBook, because DHIS docs should be translated into many other languages too.
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.
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.
I prefer XMLSpy, but this a personal preference, and I am used to
using it. It is a commercial product, but very good.
As for free products, Vex is pretty good and simple, but not sure it
is actively maintained. XMLMind was pretty good as well, but not quite
as easy to use as Vex.
If you prefer text based editors, JEdit is a good choice. Notepad++
for Windows users may be an option as well.
I have committed a portion of the GIS user manual, along with a HTML
file with one of the many XSLs availble for DocBook format in the docs
section for review. If there is enough interest, I will go ahead and
convert the rest of the document.
Best regards,
jason
Regards,
Jason
···
On 9/10/09, Lars Helge Øverland <larshelge@gmail.com> wrote:
Hi Jason, this looks interesting, can you recommend a docbook editor?
Lars
On Wed, Sep 9, 2009 at 8:31 PM, Jason Pickering > <jason.p.pickering@gmail.com >> wrote:
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.
So the only thing to be aware of using a format such as docbook, is that it tends to slow down the process of keeping the information uptodate. Checking the documentation into the version control system, and not being able to correct the documentation the same place as you are reading it, is a significant barrier. It will not exactly make it easier to invite new non-developers to contribute. A web based documentation solution (a wiki or something) would make that much easier.
On the other hand, if the alternative is office documents (as I guess it realistically is here), docbook is a better choice. So I´m not trying to kill the progress, just raising the issue
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
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@gmail.com 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
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...
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@gmail.com> 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
I can certainly see very good arguments on both sides, have to think about it a bit more. Just wanted everyone to know that there is something called DocBook wiki:
Let’s research these options a bit before deciding.
k
···
On Thu, Sep 10, 2009 at 8:33 PM, Knut Staring knutst@gmail.com wrote:
I can certainly see very good arguments on both sides, have to think about it a bit more. Just wanted everyone to know that there is something called DocBook wiki: http://doc-book.sourceforge.net/homepage/
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.
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.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
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.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
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.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
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.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
There are a couple of stylesheets out there which can do that - google xhtml2docbook
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
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.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
I will have a look at odf2docbook. It is just implemented as an xslt filter in openoffice so I should be able to get it out.
If there are word documents with reasonable structure (highly unlikely!!) then this might be a shortcut to getting a first pass going. Otherwise, from word save as xhtml (I presume it can do that) and transform that to docbook.
Aha, there is a user manual, on yet another server! Never knew about this one.
Wow, there really is a lot of material out there, and it is going to be a monumental task to get into into some type of “proper” form.
Well, I am willing to try and coordinate the initial pass at getting the documentation into DocBook, but it will have to be a team effort. This was one of my arguments for moving towards this format, as it should allow collaborative work. This will have to be done in my “spare” time, but I am willing to give it a try, assuming that everyone else is on board, and this is the direction the community wants to go. It will be a lot of work, but it seems that the long-term advantages are abundant.
I would still be interested to hear what the technical writer to be engaged by HMN has to say, as we definitely do not want to jump off a cliff here.
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.
I want to emphasize this argument: We have decided earlier to have an integrated dynamic help function in dhis2, and we already have a simple solution implemented which we can build on. Still, syncronizing the content of this help function with the general documentation effort would be desirable (and necessary). Going for an xml format such as docbook and locating the help file inside the repo will solve this issue. Choosing a wiki will demand lots of manual work.
Ola and I agree with going for DocBook - so please don’t hesitate, Jason. That said, we should look into ways of making it easy for people to contribute. An initial approach would be for contributors to send their material to you, and you make sure it fits in DocBook.
The changes with release 2.0.2 does probably mean a new manual should be created. Some material from the previous user manual may still be suitable: http://folk.uio.no/knutst/pub/usermanual/
No seriously, cross-platform and multilingual issues should not be a problem. There are many possibilities, including Eclipse for the devs.