dhis2-devs team mailing list archive

[johansa@xxxxxxxxxx]

Thanks Jason

Much appreciated, clap clap!(or to use dev-lingua, mch a9d; -clp clp)
As soon as I get some time, I can try it out. If I manage, then it's both
fool proof and africa proof (in sierra leone)

Johan

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