dhis2-devs team mailing list archive

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

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
>
>
>
>