dhis2-devs team mailing list archive

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

Hi Jens and others,
I have added a bit more detail to the document about how to create
documentation. I am attaching a PDF file along with this email. As you
can see, we still need to do a bit of work on rendering the PDF
doucment properly (URLs are not rendered as they should be) but
otherwise, I think the document should be readable, and hopefully
enough to get started. I am just in the process of commiting the
changes to the documentation branch.

I would be happy to help you get started, as I would really like to
see this part of DHIS take off a bit. High quality documentation is
sorely needed. The transition to docbook as a primary source of
documentation should not hinder this process, but if too many people
find it too difficult to use "bzr" and edit XML documents (even with
nice editors) then we really need to re-evaluate whether it is
feasible or not.

Hope the doucment helps. Let me know if you need further guidance.

Best regards,
Jason


On Thu, Sep 24, 2009 at 9:54 PM, Jens Kaasbøll <jensj@xxxxxxxxxx> wrote:
> Jason and others,
> Thanks for this initiative. A structured approach to documentation will be
> the right, professional way.
>
> However, in the area of user documentation and tutorials, there will be
> people like me, who are not software developers, and who do not understand
> what we should do with the code
> bzr pull lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
>
> There are also people who could contribute, who come from the health
> background without being computer scientists, and who would also feel
> alienated by the ideas of XML, structured documents, etc. I could take on
> the challenge of trying to accommodate these, but then I would need
> - to be included in the documentation group
> - to get a crash course on bzrs and other TLAs.
>
> Best regards,
> Jens Kaasbøll
> Univ Oslo
>
>
> On 17.09.2009 22:59, Jason Pickering wrote:
>>
>> OK, i think i solved that problem as well. I created a new team
>> (dhis2-documenters). The new branch is available here.
>>
>> bzr pull lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
>>
>> Let me know if you want to be added to this team.  I think I have done
>> everything correctly, but not sure.
>>
>> Best regards,
>> Jason
>>
>>
>>
>> 2009/9/17 Jason Pickering <jason.p.pickering@xxxxxxxxx>:
>>>
>>> I went ahead and created a separate branch for the docbook
>>> documentation effort and it can be found here.
>>>
>>> bzr branch lp:~dhis2-devs/dhis2/dhis2-docbook-docs
>>>
>>> I am not that familiar with Launchpad, but it would seem that perhaps
>>> a separate group/team should be added as the owner should be added
>>> instead of the DHIS2 devs so that access could be controlled?
>>>
>>> Regards,
>>> Jason
>>>
>>>
>>> 2009/9/17 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
>>>>>
>>>>>
>>>>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~dhis2-devs
>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~dhis2-devs
>> More help   : https://help.launchpad.net/ListHelp
>
>

Attachment: dhis2_documentation_guide.pdf
Description: Adobe PDF document