Hi Lars,
Glad to see you had a chance to review it. I hope it will catch on. I know it is a bit more effort, but with all those semi-WYSIWYG editors out there, it is not much more difficult that creating a Word document. There are going to be some compromises of course in terms of layout initially. The HTML is rendered a bit better now with the addition of a style sheet, but it will probably take a lot more tweaking. However, the important thing to remember is that any documentation, even if it is a bit ugly, is better than none at all! We still need to figure out what to do with the DokuWiki and other pockets of documentation out there.
I think that creation of a separated branch would be the way to go in the long run. Most people that want to contribute to documentation do not generally need all of the source code as well, and if the devs want to contribute to the documentation, well, it is simple enough to do this. Before we do this however, I think we should somehow formally endorse that DocBook (or similar presentation neutral XML documents) is the way we want to go.
I am still willing to coordinate the effort for the time being. This may be a better short-term solution, so that we can continue to guage what the interest is in heading this direction with the documentation. Thinking long-term, I suppose it is no problem that the documentation is in a separated branch? Ideally, with some sort of integrated help system that is able to access the documentation directly, we would need to include the documentation build as part of the entire DHIS2 build process. I guess this is not an issue, but as I have said previously, maven is just juju for me. But thank goodness, we have Lars. :)
Best regards,
jason
2009/9/17 Lars Helge Øverland <larshelge@xxxxxxxxx>
On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering <jason.p.pickering@xxxxxxxxx> wrote:
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway..
Just execute..
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.
There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
You can read about it here.
http://docbkx-tools.sourceforge.net/
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason
Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called "dhis-documentation-docbook" and used the same name for the project's artifact id. Also removed the packaging: pom element, which now makes it possible to execute "mvn eclipse:eclipse" and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
http://www.syntext.com/products/serna-free/
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don't want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work... I hope other people using the system will follow his example and contribute to this process.
cheers
Lars
