Documentation

Hi there,

there has recently been some nice contributions to the documentation writing, which is great.

I was wondering about this:

Could we quickly and together come up with an overall table of contents? This
will be a useful starting point, give us an overview of what we need to
write and make it easier to delegate tasks.

  1. Should we assemble all the xml files / modules into one file? To
    me its more sensible to have all of it in one document. Or is there a
    mvn docbkx goal for aggregating all the docs?

regards, Lars

Hi there,

there has recently been some nice contributions to the documentation writing, which is great.

I was wondering about this:

  1. Could we quickly and together come up with an overall table of contents? This will be a useful starting point, give us an overview of what we need to write and make it easier to delegate tasks.

This is very much needed for consolidating all the material we already have and highlight what is missing. A beginning has been done here:

http://www.openhealthconsortium.org/wiki/doku.php?id=dhis_2_documentation&s[]=manual

  1. Should we assemble all the xml files / modules into one file? To me its more sensible to have all of it in one document.

Agree. Though it may make some sense to keep it separate while we are converting from Word, so several people can more easily work in parallel. But there is a big collation/consolidation task waiting on us, related to an overall structure as defined above. Another question is whether we should have one strictly technical part (this button does this) and another more didactic part (as the Indian manual is - with explanations of FOSS etc). It may be that professional help from a technical writer would be useful for such structuring.

···

2009/11/18 Lars Helge Øverland larshelge@gmail.com

Or is there a mvn docbkx goal for aggregating all the docs?

regards, Lars


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Cheers,
Knut Staring

I think in the context of docbook several articles can be assembled

into a book through a seperate xml file. I would suggest to keep the

current article structure but assemble everything through a separate

structure file to link them together. I can have a first stab at this

for the user manual unless there are other takers.

···

2009/11/18 Jason Pickering jason.p.pickering@gmail.com

I think in the context of docbook several articles can be assembled

into a book through a seperate xml file. I would suggest to keep the

current article structure but assemble everything through a separate

structure file to link them together.

That’s just fine with me.

I can have a first stab at this

for the user manual unless there are other takers.

That would be great.

···

2009/11/18 Lars Helge Øverland larshelge@gmail.com

2009/11/18 Jason Pickering jason.p.pickering@gmail.com

Yes that might be sensible.

OK so we have a few tasks:

  1. Write a draft table of contents. Suggest how we structure the document re what Knut says above.

  2. Merge what we already have into our document. Sources are the Indian manual, the openhealthconsortium wiki, the help file inside dhis-web-commons-resources. More?

  3. Create a structure file which assembles the modules into one document. (Jason)

If we get this in place we can later assign sub-tasks to people dependent on experience/knowledge, which will be easier to take on.

Any volunteers?

I am more than willing to contribute by documenting the inner workings of dhis2 but I feel there are people in the network with more experience from the health worker / user perspective who will do these tasks better (rather than a developer).

Lars

···

2009/11/18 Knut Staring knutst@gmail.com

2009/11/18 Lars Helge Øverland larshelge@gmail.com

Hi there,

there has recently been some nice contributions to the documentation writing, which is great.

I was wondering about this:

  1. Could we quickly and together come up with an overall table of contents? This will be a useful starting point, give us an overview of what we need to write and make it easier to delegate tasks.

This is very much needed for consolidating all the material we already have and highlight what is missing. A beginning has been done here:

http://www.openhealthconsortium.org/wiki/doku.php?id=dhis_2_documentation&s[]=manual

  1. Should we assemble all the xml files / modules into one file? To me its more sensible to have all of it in one document.

Agree. Though it may make some sense to keep it separate while we are converting from Word, so several people can more easily work in parallel. But there is a big collation/consolidation task waiting on us, related to an overall structure as defined above. Another question is whether we should have one strictly technical part (this button does this) and another more didactic part (as the Indian manual is - with explanations of FOSS etc). It may be that professional help from a technical writer would be useful for such structuring.

Hi there,

there has recently been some nice contributions to the documentation writing, which is great.

I was wondering about this:

  1. Could we quickly and together come up with an overall table of contents? This will be a useful starting point, give us an overview of what we need to write and make it easier to delegate tasks.

This is very much needed for consolidating all the material we already have and highlight what is missing. A beginning has been done here:

http://www.openhealthconsortium.org/wiki/doku.php?id=dhis_2_documentation&s[]=manual

  1. Should we assemble all the xml files / modules into one file? To me its more sensible to have all of it in one document.

Agree. Though it may make some sense to keep it separate while we are converting from Word, so several people can more easily work in parallel. But there is a big collation/consolidation task waiting on us, related to an overall structure as defined above. Another question is whether we should have one strictly technical part (this button does this) and another more didactic part (as the Indian manual is - with explanations of FOSS etc). It may be that professional help from a technical writer would be useful for such structuring.

Yes that might be sensible.

OK so we have a few tasks:

  1. Write a draft table of contents. Suggest how we structure the document re what Knut says above.

  2. Merge what we already have into our document. Sources are the Indian manual, the openhealthconsortium wiki, the help file inside dhis-web-commons-resources. More?

Oh yes, munch more out there:

http://208.76.222.114/confluence/display/DOC/Home
http://folk.uio.no/olati/filer/Customising_DHIS2.pdf (linked from http://208.76.222.114/confluence/display/DOC/Home,a BEANISH deliverable, has some conecptual stuff on data elements, indicators, data sets etc, design principles from paper to db)

https://answers.launchpad.net/dhis2
https://answers.launchpad.net/dhis2/+faqshttp://208.76.222.114/confluence/download/attachments/8489/Comprehensive+HIS+training.zip?version=1 (it’s the SL training and manual)

http://208.76.222.114/confluence/download/attachments/8489/DHIS+Short+user+manual.doc?version=1 (Sierra Leone)

http://208.76.222.114/confluence/display/DHIS1/DHIS+1.4 (some useful conceptual explanations by Calle here (survey data, onchange periods etc.
http://208.76.222.114/confluence/download/attachment/466/DHIS+1.4+maintenance+manual+for+Zanzibar.doc?version=1 (needs a bit of a rewrite for DHIS 2, but design principles part should be useful)

Tanzania manual for DHIS 2 (Mahundi is working on it)
Tanzania DHIS 2 data set design document, best practices for design (Lungu is working on this)
VN user manuals for DHIS2 (needs translation)

  1. Create a structure file which assembles the modules into one document. (Jason)

If we get this in place we can later assign sub-tasks to people dependent on experience/knowledge, which will be easier to take on.

Any volunteers?

It always work better if we can link this directly to needs or even budgeted project tasks in countries implementing DHIS. A lot of documentation is happening here already, but needs coordination and common tools.

I am sure Tanzania, India, Sierra Leone, and Malawi are all right now either planning to write, are already writing new manuals, or are updating their existing manuals.

These are the processes that should drive the manual writing and then maybe more experienced DHIS implementers can do some quality control and editing at some point.

···

2009/11/18 Lars Helge Øverland larshelge@gmail.com

2009/11/18 Knut Staring knutst@gmail.com

2009/11/18 Lars Helge Øverland larshelge@gmail.com

I am more than willing to contribute by documenting the inner workings of dhis2 but I feel there are people in the network with more experience from the health worker / user perspective who will do these tasks better (rather than a developer).

Lars


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp

It seems we are using the article style which we can easily enough translate into a book style (or two) with the articles being chapters.

Also I notice the mvn plugin is using docbook 4.4. All of the latest docbook dev is happening with v5. Not sure if its a matter of changing the pom.xml or whether v5 is not in mvn repository. I can look at this stuff later - at the moment am about to lose my table and internet connection …

Regards
Bob

···

2009/11/18 Knut Staring knutst@gmail.com

2009/11/18 Lars Helge Øverland larshelge@gmail.com

Hi there,

there has recently been some nice contributions to the documentation writing, which is great.

I was wondering about this:

  1. Could we quickly and together come up with an overall table of contents? This will be a useful starting point, give us an overview of what we need to write and make it easier to delegate tasks.

This is very much needed for consolidating all the material we already have and highlight what is missing. A beginning has been done here:

http://www.openhealthconsortium.org/wiki/doku.php?id=dhis_2_documentation&s[]=manual

  1. Should we assemble all the xml files / modules into one file? To me its more sensible to have all of it in one document.

Agree. Though it may make some sense to keep it separate while we are converting from Word, so several people can more easily work in parallel. But there is a big collation/consolidation task waiting on us, related to an overall structure as defined above. Another question is whether we should have one strictly technical part (this button does this) and another more didactic part (as the Indian manual is - with explanations of FOSS etc). It may be that professional help from a technical writer would be useful for such structuring.

Or is there a mvn docbkx goal for aggregating all the docs?

regards, Lars


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Cheers,
Knut Staring


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

···

On Wed, Nov 18, 2009 at 1:06 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

It seems we are using the article style which we can easily enough translate into a book style (or two) with the articles being chapters.

Also I notice the mvn plugin is using docbook 4.4. All of the latest docbook dev is happening with v5. Not sure if its a matter of changing the pom.xml or whether v5 is not in mvn repository. I can look at this stuff later - at the moment am about to lose my table and internet connection …

OK so we have a few tasks:

  1. Write a draft table of contents. Suggest how we structure the document re what Knut says above.

  2. Merge what we already have into our document. Sources are the Indian manual, the openhealthconsortium wiki, the help file inside dhis-web-commons-resources. More?

Oh yes, munch more out there:

http://208.76.222.114/confluence/display/DOC/Home

http://folk.uio.no/olati/filer/Customising_DHIS2.pdf (linked from http://208.76.222.114/confluence/display/DOC/Home,a BEANISH deliverable, has some conecptual stuff on data elements, indicators, data sets etc, design principles from paper to db)

https://answers.launchpad.net/dhis2
https://answers.launchpad.net/dhis2/+faqs http://208.76.222.114/confluence/download/attachments/8489/Comprehensive+HIS+training.zip?version=1 (it’s the SL training and manual)

http://208.76.222.114/confluence/download/attachments/8489/DHIS+Short+user+manual.doc?version=1 (Sierra Leone)

http://208.76.222.114/confluence/display/DHIS1/DHIS+1.4 (some useful conceptual explanations by Calle here (survey data, onchange periods etc.

http://208.76.222.114/confluence/download/attachment/466/DHIS+1.4+maintenance+manual+for+Zanzibar.doc?version=1 (needs a bit of a rewrite for DHIS 2, but design principles part should be useful)

Tanzania manual for DHIS 2 (Mahundi is working on it)
Tanzania DHIS 2 data set design document, best practices for design (Lungu is working on this)
VN user manuals for DHIS2 (needs translation)

Thanks for providing this list.

  1. Create a structure file which assembles the modules into one document. (Jason)

If we get this in place we can later assign sub-tasks to people dependent on experience/knowledge, which will be easier to take on.

Any volunteers?

It always work better if we can link this directly to needs or even budgeted project tasks in countries implementing DHIS. A lot of documentation is happening here already, but needs coordination and common tools.

I am sure Tanzania, India, Sierra Leone, and Malawi are all right now either planning to write, are already writing new manuals, or are updating their existing manuals.

These are the processes that should drive the manual writing and then maybe more experienced DHIS implementers can do some quality control and editing at some point.

Yes I agree with this, but with volunteers I was referring to task 1. and 2. above. It will be easier to get people to contribute if we have an overview of what needs to be written and an existing document which people can append to rather than starting from scratch.

Notice the size of the binary… 0 bytes

Basically, Jason wants 4.2 and Bob wants bleeding edge. Me, I´m more of the pragmatic type :slight_smile:

Jo

···

Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

Doh…

···

On Wed, Nov 18, 2009 at 4:00 PM, Jo Størset storset@gmail.com wrote:

Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

Notice the size of the binary… 0 bytes

I do not have a strong opinion about which version to use, mostly out
of ignorance, but somewhat based on practicality. We are using a very
small subset (at the moment) of the total number of DocBook tags, so I
am not 100% about whether we need to be on the bleeding edge. My
recommendation of using version 4.x is based on what is available with
the WYSIWYG editor, Serna Free, which support version 4.2 out of the
box. There could be compelling reasons to use a later version of the
schema, but they are not apparent to me. Based on our immediate
requirements to have a somewhat more streamlined set of documents, the
editors that are practical for both geeks and those less inclined to
use VI for editing DocBook, it would make sense to stick with
something that is perhaps not bleeding edge, but practical. I think
the changes Jo has made to the pom are great and significantly ease
the building on the documentation on my side (working over an
incredibly bad link).

Unless there are other reasons, I think we should tread softly, and
stick with what works for now.

···

On Wed, Nov 18, 2009 at 5:02 PM, Lars Helge Øverland <larshelge@gmail.com> wrote:

On Wed, Nov 18, 2009 at 4:00 PM, Jo Størset <storset@gmail.com> wrote:

Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

Notice the size of the binary.. 0 bytes

Doh..

_______________________________________________
Mailing list: DHIS 2 developers in Launchpad
Post to : dhis2-devs@lists.launchpad.net
Unsubscribe : DHIS 2 developers in Launchpad
More help : ListHelp - Launchpad Help

Agree with being practical - which probably means old-fashioned in this case, unless there are very compelling features in version 5. Just wanted to note that I personally have found XML Mind more suitable and faster than Serna Free, and it is good in that it readily displays the path to resources like images.

Knut

···

2009/11/18 Jason Pickering jason.p.pickering@gmail.com

I do not have a strong opinion about which version to use, mostly out

of ignorance, but somewhat based on practicality. We are using a very

small subset (at the moment) of the total number of DocBook tags, so I

am not 100% about whether we need to be on the bleeding edge. My

recommendation of using version 4.x is based on what is available with

the WYSIWYG editor, Serna Free, which support version 4.2 out of the

box. There could be compelling reasons to use a later version of the

schema, but they are not apparent to me. Based on our immediate

requirements to have a somewhat more streamlined set of documents, the

editors that are practical for both geeks and those less inclined to

use VI for editing DocBook, it would make sense to stick with

something that is perhaps not bleeding edge, but practical. I think

the changes Jo has made to the pom are great and significantly ease

the building on the documentation on my side (working over an

incredibly bad link).

Unless there are other reasons, I think we should tread softly, and

stick with what works for now.

On Wed, Nov 18, 2009 at 5:02 PM, Lars Helge Øverland > > larshelge@gmail.com wrote:

On Wed, Nov 18, 2009 at 4:00 PM, Jo Størset storset@gmail.com wrote:

Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

Notice the size of the binary… 0 bytes

Doh…


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Cheers,
Knut Staring

I also have no great knowledge of docbook so I guess for that reason, also no really compelling reason to move to 5. Just been reading material on the docbook website which suggests 4.x is end of life. And 5 is hardly bleeding edge at this point. And the fact that version 5 is namespaced and has a relaxng schema rather than the older dtd. Though I concede these are not issues which bother most people. But as long as the schema is available there is no good reason not to be able to use either version in any xml schema-aware editor. In which case I would probably use 5. Emacs, oxygen, XMLmind and probably editx will allow you to edit valid docbook 5.0. I haven’t really surveyed all the other tools, but if it really is awkward then I guess we stick with 4.x for now (mind you 4.5 is the last of the 4 series, not 4.4).

Bob

···

2009/11/18 Knut Staring knutst@gmail.com

Agree with being practical - which probably means old-fashioned in this case, unless there are very compelling features in version 5. Just wanted to note that I personally have found XML Mind more suitable and faster than Serna Free, and it is good in that it readily displays the path to resources like images.

Knut

2009/11/18 Jason Pickering jason.p.pickering@gmail.com

I do not have a strong opinion about which version to use, mostly out

of ignorance, but somewhat based on practicality. We are using a very

small subset (at the moment) of the total number of DocBook tags, so I

am not 100% about whether we need to be on the bleeding edge. My

recommendation of using version 4.x is based on what is available with

the WYSIWYG editor, Serna Free, which support version 4.2 out of the

box. There could be compelling reasons to use a later version of the

schema, but they are not apparent to me. Based on our immediate

requirements to have a somewhat more streamlined set of documents, the

editors that are practical for both geeks and those less inclined to

use VI for editing DocBook, it would make sense to stick with

something that is perhaps not bleeding edge, but practical. I think

the changes Jo has made to the pom are great and significantly ease

the building on the documentation on my side (working over an

incredibly bad link).

Unless there are other reasons, I think we should tread softly, and

stick with what works for now.

On Wed, Nov 18, 2009 at 5:02 PM, Lars Helge Øverland > > > > larshelge@gmail.com wrote:

On Wed, Nov 18, 2009 at 4:00 PM, Jo Størset storset@gmail.com wrote:

Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

Notice the size of the binary… 0 bytes

Doh…


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Cheers,
Knut Staring


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp

final PS:
There is no harm working with the pieces in article style for now. But if we want integrated TOC, index, front-matter etc we will get these better from a book style. I think many of the wysiwg tools may just produce an article header by default. Probably can be tweaked - or just reassemble the pieces later ie transform articles into chapters.

···

2009/11/18 Bob Jolliffe bobjolliffe@gmail.com

I also have no great knowledge of docbook so I guess for that reason, also no really compelling reason to move to 5. Just been reading material on the docbook website which suggests 4.x is end of life. And 5 is hardly bleeding edge at this point. And the fact that version 5 is namespaced and has a relaxng schema rather than the older dtd. Though I concede these are not issues which bother most people. But as long as the schema is available there is no good reason not to be able to use either version in any xml schema-aware editor. In which case I would probably use 5. Emacs, oxygen, XMLmind and probably editx will allow you to edit valid docbook 5.0. I haven’t really surveyed all the other tools, but if it really is awkward then I guess we stick with 4.x for now (mind you 4.5 is the last of the 4 series, not 4.4).

Bob

2009/11/18 Knut Staring knutst@gmail.com

Agree with being practical - which probably means old-fashioned in this case, unless there are very compelling features in version 5. Just wanted to note that I personally have found XML Mind more suitable and faster than Serna Free, and it is good in that it readily displays the path to resources like images.

Knut

2009/11/18 Jason Pickering jason.p.pickering@gmail.com

I do not have a strong opinion about which version to use, mostly out

of ignorance, but somewhat based on practicality. We are using a very

small subset (at the moment) of the total number of DocBook tags, so I

am not 100% about whether we need to be on the bleeding edge. My

recommendation of using version 4.x is based on what is available with

the WYSIWYG editor, Serna Free, which support version 4.2 out of the

box. There could be compelling reasons to use a later version of the

schema, but they are not apparent to me. Based on our immediate

requirements to have a somewhat more streamlined set of documents, the

editors that are practical for both geeks and those less inclined to

use VI for editing DocBook, it would make sense to stick with

something that is perhaps not bleeding edge, but practical. I think

the changes Jo has made to the pom are great and significantly ease

the building on the documentation on my side (working over an

incredibly bad link).

Unless there are other reasons, I think we should tread softly, and

stick with what works for now.

On Wed, Nov 18, 2009 at 5:02 PM, Lars Helge Øverland > > > > > > larshelge@gmail.com wrote:

On Wed, Nov 18, 2009 at 4:00 PM, Jo Størset storset@gmail.com wrote:

Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:

5.0 is available:

http://mvnrepository.com/artifact/org.docbook/docbook-xml

Notice the size of the binary… 0 bytes

Doh…


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp


Cheers,
Knut Staring


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp

Hi Knut,

Please note my recommendation both in the documentation guide as well
as on this mailing list NOT to use XML Mind. There were a number of
problems that I encountered when trying to collaborate with the Viet
Nam team with this program. XML Mind seems to insert a number of
elements silently as well as "pretty printing" the XML behind the
scenes , inserting a lot of line breaks, which are really uncessary
for DocBook. Some DocBook renderers will respect these line breaks,
which makes document production more tricky.

I agree that it is easy to use. I prefer it when compared to Serna as
it is certainly more intuitive. However given the issues that I
experienced when working on the Excel report document from Viet Nam, I
felt that it was not an appropriate tool to use when multiple people
may be collaborating on a document with different DocBook editors.

Best regards,
Jason

···

On 11/18/09, Knut Staring <knutst@gmail.com> wrote:

Agree with being practical - which probably means old-fashioned in this
case, unless there are very compelling features in version 5. Just wanted to
note that I personally have found XML Mind more suitable and faster than
Serna Free, and it is good in that it readily displays the path to resources
like images.

Knut

2009/11/18 Jason Pickering <jason.p.pickering@gmail.com>

I do not have a strong opinion about which version to use, mostly out
of ignorance, but somewhat based on practicality. We are using a very
small subset (at the moment) of the total number of DocBook tags, so I
am not 100% about whether we need to be on the bleeding edge. My
recommendation of using version 4.x is based on what is available with
the WYSIWYG editor, Serna Free, which support version 4.2 out of the
box. There could be compelling reasons to use a later version of the
schema, but they are not apparent to me. Based on our immediate
requirements to have a somewhat more streamlined set of documents, the
editors that are practical for both geeks and those less inclined to
use VI for editing DocBook, it would make sense to stick with
something that is perhaps not bleeding edge, but practical. I think
the changes Jo has made to the pom are great and significantly ease
the building on the documentation on my side (working over an
incredibly bad link).

Unless there are other reasons, I think we should tread softly, and
stick with what works for now.

On Wed, Nov 18, 2009 at 5:02 PM, Lars Helge Øverland >> <larshelge@gmail.com> wrote:
>
>
> On Wed, Nov 18, 2009 at 4:00 PM, Jo Størset <storset@gmail.com> wrote:
>>
>> Den 18. nov. 2009 kl. 15.08 skrev Lars Helge Øverland:
>>
>> 5.0 is available:
>>
>> http://mvnrepository.com/artifact/org.docbook/docbook-xml
>>
>> Notice the size of the binary.. 0 bytes
>
>
> Doh..
>
> _______________________________________________
> Mailing list: DHIS 2 developers in Launchpad
> Post to : dhis2-devs@lists.launchpad.net
> Unsubscribe : DHIS 2 developers in Launchpad
> More help : ListHelp - Launchpad Help
>
>

_______________________________________________
Mailing list: DHIS 2 developers in Launchpad
Post to : dhis2-devs@lists.launchpad.net
Unsubscribe : DHIS 2 developers in Launchpad
More help : ListHelp - Launchpad Help

--
Cheers,
Knut Staring

I have had this message highlighted for a while and wanted to respond
in more detail to a few points.

1. Write a draft table of contents. Suggest how we structure the document

This is now done in the dhis2_user_manual_en.xml document.

2. Merge what we already have into our document. Sources are the Indian
manual, the openhealthconsortium wiki, the help file inside
dhis-web-commons-resources. More?

I am still working on the other user manuals from India here..
ttp://folk.uio.no/knutst/pub/usermanual/

Some of them, particularly the reporting manual, need to be completely
rewritten, as the current manual is either too specific for India, or
not inline with the current set of functionality after the inclusion
of the Excel reporting module in trunk. I think that modules 5,6,7
will need to be rewritten from scratch. 8 (data maintainence) is in
pretty good shape, but will need some rework. 9 has been superceded by
the GIS document. module 10 (installation on widows) i am not sure
about. we should probably place this at the top of the main user
manual, and generalize it to both windows (installer if it is working,
DHIS2 Live) and Linux (Debian installer, DHIS 2 Live and a full-blown
Tomcat/Postgres setup).

...

Thanks for providing this list.

There was a bit set of links here. I have not take a look at any of
this in any level of detail, but my feeling is that it would take
quite a bit of work to synthesize it all together into a single
document. I think the Indian manuals provide a quite comprehensive set
of initial documents, but again, will require more work to generalize
them, and bring them up to date with the new functionality.

3. Create a structure file which assembles the modules into one document.
(Jason)

This has been done as outlined above. The first four Indian user
manuals, the GIS user manual, the documentation guide, the Excel
reporting guide and the technical architecture document have been
assembled into a single document. I think there is another document on
aggregation which I have not included yet.

Any volunteers?

Well, I am sitting here in Lusaka at the beginning of the rainy season
and hear nothing but crickets and tree frogs....chirp chirp chirp. I
will do what I can in my spare time, but some more help would be
great, especially from those that have become part of the
documentation team. :slight_smile:

It always work better if we can link this directly to needs or even
budgeted project tasks in countries implementing DHIS. A lot of
documentation is happening here already, but needs coordination and common
tools.

This is the whole point of a structure like DocBook. Documents can be
segmented into various parts and reassembled as necessary, depending
on the requirements. Different implementers in different countries
should be able to pick and choose what they want, depending on the
exact requirements.

I am sure Tanzania, India, Sierra Leone, and Malawi are all right now
either planning to write, are already writing new manuals, or are updating
their existing manuals.

This is great. Can you have them contact me?

These are the processes that should drive the manual writing and then
maybe more experienced DHIS implementers can do some quality control and
editing at some point.

Agreed. I can add whoever satisfies these requirements to the
documentation team.

Lars has also suggested that we might merge the documentation branch
back into trunk. I think this is not a good idea at this point, as in
the long run, there will be a different set of contributors, I hope. I
would suggest that we explore other solutions like possibly symlinking
the two branches (not even sure this is possible), so that some level
of control can be maintained over each of them. I do not have
particularly strong feelings on this either way, but it seems to feel
right to keep them separate to me.

As you can tell, I am feeling a bit frisky tonight, and want to try
and continue the bit of momentum that we have with the documentation
effort. Any suggestions, flames, or contributions welcome.

Best regards,
Jason

Thanks a lot for this contribution Jason. The docs is really starting to look better.

I will talk to Calle and see if he has some inputs. HISP SA has apparently produced a lot of material which could be borrowed from.

Re the inclusion in trunk I have changed my mind anyway, the size of the doc branch is increasing quickly with all the images and would add too much size for people only wanting the code.

Lars

Hi Lars,
Agreed for now.

I have some extra time on my hands right now, so I can try and work on
this a bit more if you get some more material.

regards,
Jason

···

2009/12/8 Lars Helge Øverland <larshelge@gmail.com>:

Thanks a lot for this contribution Jason. The docs is really starting to
look better.

I will talk to Calle and see if he has some inputs. HISP SA has apparently
produced a lot of material which could be borrowed from.

Re the inclusion in trunk I have changed my mind anyway, the size of the doc
branch is increasing quickly with all the images and would add too much size
for people only wanting the code.

Lars

Hi,

I also like the way the manual is shaping up.

There is at least one major part missing though and that is what often is called database maintenance or design.
with three major subsections:

1)Orgunits, hierarchies, group sets and groups:

What are they, how to set them up, what is the recommended usage.

2)Data elements, categories, datasets, groups and group sets:
What are data element, dimensions, and data sets? How to go from a paper form to a DHIS dataset?

best practices, examples

How much from the Indian module can we use here?

And there are text on this on the help page as well that can be used:

http://dhis.uio.no/demo/dhis-web-commons-about/help.action

I think there are some useful text in the administrators manual I wrote some years ago as well (http://folk.uio.no/olati/filer/Customising_DHIS2.pdf).

I can help to fill in the gaps here.

And then maybe another crucial chapter missing is “data analysis and reporting”, at least an intro to that with three core building blocks:

  1. Aggregation
    how it takes place (over time, over space, avg/sum, aggregation levels, datamart

This is already in docbook format and needs to go into the main document

  1. Indicators
    what are they, types, formulas, factor, annualisation
    The help page is quite good here actually.

  2. Report tables

Already in docbook I think. At least on openhealthconsortium wiki and launchpad FAQ

Then the manual can go on to all the other reporting stuff like charts, BIRT, jasper, excel, pivots, GIS, what have you

I can give you a hand with this Jason, but great if you come up with a first draft that I (and hopefully others) can work from.

Should be try to come up with a more comprehensive table of contents in the main doc (including stuff that is not written up) to get a better overview of the gaps?

Ola

···

2009/12/8 Jason Pickering jason.p.pickering@gmail.com

Hi Lars,

Agreed for now.

I have some extra time on my hands right now, so I can try and work on

this a bit more if you get some more material.

regards,

Jason

2009/12/8 Lars Helge Øverland larshelge@gmail.com:

Thanks a lot for this contribution Jason. The docs is really starting to

look better.

I will talk to Calle and see if he has some inputs. HISP SA has apparently

produced a lot of material which could be borrowed from.

Re the inclusion in trunk I have changed my mind anyway, the size of the doc

branch is increasing quickly with all the images and would add too much size

for people only wanting the code.

Lars


Mailing list: https://launchpad.net/~dhis2-devs

Post to : dhis2-devs@lists.launchpad.net

Unsubscribe : https://launchpad.net/~dhis2-devs

More help : https://help.launchpad.net/ListHelp