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
