DHIS2 Documentation for Metadata Sync and Versioning

Support - Assistance technique
1

Hi Devs

We are now beginning to write documentation for the Metadata Sync and Versioning core features.

What are the guidelines for doing this documentation? What tools/wiki are being used for documentation at DHIS. It would be good if you could point us to it.

As we understand that there are 3 manuals

  • Developer guide

  • User guide

  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

  • The new task (Metadata sync task)

  • Metadata Versioning and Metadata Sync as a concept.

  • Best practices around the Metadata versioning setup.

  • Optimization of the initial setup of new field instances given the central-field deployment strategy

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

It would be good if you could help us get started.

···

With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

2

Hi Vanya,

Please have a look here

http://dhis2.github.io/dhis2-docs/2.22/en/implementer/html/apa.html

which describes in a fair amount of detail how to get started with the documentation.

You can just submit a pull request through the GitHub repo.

Let us know if you need further information.

Regards,

Jason

···

On Mon, Jun 6, 2016 at 2:44 PM, Vanya Seth vanyas@thoughtworks.com wrote:

Hi Devs

We are now beginning to write documentation for the Metadata Sync and Versioning core features.

What are the guidelines for doing this documentation? What tools/wiki are being used for documentation at DHIS. It would be good if you could point us to it.

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).
  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy
  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]
  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

It would be good if you could help us get started.

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

–

Jason P. Pickering
email: jason.p.pickering@gmail.com
tel:+46764147049

3

Thanks for the information Jason.

Regards

Vanya

···

On Mon, Jun 6, 2016 at 6:26 PM, Jason Pickering jason.p.pickering@gmail.com wrote:

Hi Vanya,

Please have a look here

http://dhis2.github.io/dhis2-docs/2.22/en/implementer/html/apa.html

which describes in a fair amount of detail how to get started with the documentation.

You can just submit a pull request through the GitHub repo.

Let us know if you need further information.

Regards,

Jason

–

On Mon, Jun 6, 2016 at 2:44 PM, Vanya Seth vanyas@thoughtworks.com wrote:

Hi Devs

We are now beginning to write documentation for the Metadata Sync and Versioning core features.

What are the guidelines for doing this documentation? What tools/wiki are being used for documentation at DHIS. It would be good if you could point us to it.

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).
  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy
  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]
  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

It would be good if you could help us get started.

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Jason P. Pickering
email: jason.p.pickering@gmail.com
tel:+46764147049

–

With Regards
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

4

Hi Vanya,

thanks for taking the time to document this.

···

Just some suggestions for your question on where to put what:

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

Developer guide (API docs)

  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy

I suggest a new chapter in the user manual called “Metadata synchronization” for these.

http://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

Add to settings chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch23.html

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

Add to data administration chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch22.html

It would be good if you could help us get started.

regards,

Lars

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

–

Lars Helge Øverland

Lead developer, DHIS 2

University of Oslo

Skype: larshelgeoverland

lars@dhis2.org

http://www.dhis2.org

5

Thanks for the information Lars.

Regards

Vanya

···

On Tue, Jun 7, 2016 at 7:26 AM, Lars Helge Øverland lars@dhis2.org wrote:

Hi Vanya,

thanks for taking the time to document this.

–

Just some suggestions for your question on where to put what:

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

Developer guide (API docs)

  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy

I suggest a new chapter in the user manual called “Metadata synchronization” for these.

http://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

Add to settings chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch23.html

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

Add to data administration chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch22.html

It would be good if you could help us get started.

regards,

Lars

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Lars Helge Øverland

Lead developer, DHIS 2

University of Oslo

Skype: larshelgeoverland

lars@dhis2.org

http://www.dhis2.org

–

With Regards
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

6

Hi

We have forked dhis2-docs repo to get started with the documentation for the new features. However when we try to build the just cloned repo with apache maven as mentioned in http://dhis2.github.io/dhis2-docs/2.22/en/implementer/html/apas09.html

we are getting below error

···

On Tue, Jun 7, 2016 at 10:48 AM, Vanya Seth vanyas@thoughtworks.com wrote:

Thanks for the information Lars.

Regards

Vanya

On Tue, Jun 7, 2016 at 7:26 AM, Lars Helge Øverland lars@dhis2.org wrote:

Hi Vanya,

thanks for taking the time to document this.

–
With Regards
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Just some suggestions for your question on where to put what:

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

Developer guide (API docs)

  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy

I suggest a new chapter in the user manual called “Metadata synchronization” for these.

http://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

Add to settings chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch23.html

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

Add to data administration chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch22.html

It would be good if you could help us get started.

regards,

Lars

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Lars Helge Øverland

Lead developer, DHIS 2

University of Oslo

Skype: larshelgeoverland

lars@dhis2.org

http://www.dhis2.org

–

7

Hi

I’m not aware of any extra steps needed, I just built it fine here locally… (mvn clean package), could be something local on your laptop? I see no complaints from our build server either

···

On Mon, Jun 27, 2016 at 1:59 PM, Aamer Mohammed aamerm@thoughtworks.com wrote:

Hi

We have forked dhis2-docs repo to get started with the documentation for the new features. However when we try to build the just cloned repo with apache maven as mentioned in http://dhis2.github.io/dhis2-docs/2.22/en/implementer/html/apas09.html

we are getting below error

[ERROR] Failed to execute goal com.agilejava.docbkx:docbkx-maven-plugin:2.0.17:generate-html (chunked-html-docs-implementer) on project dhis-documentation-docbook: Failed to transform dhis2_implementation_guide_en.xml. org.xml.sax.SAXParseException; systemId: file:///Users/aamerm/Documents/oca/dhis2docs/dhis2-docs/src/docbkx/en/dhis2_implementation_guide_en.xml; lineNumber: 35; columnNumber: 68; An ‘include’ failed, and no ‘fallback’ element was found. → [Help 1]

Are there any other steps apart from the ones mentioned in readme. Please suggest.

Thanks

Aamer.

–

Morten Olav Hansen

Senior Engineer, DHIS 2

University of Oslo

http://www.dhis2.org

On Tue, Jun 7, 2016 at 10:48 AM, Vanya Seth vanyas@thoughtworks.com wrote:

Thanks for the information Lars.

Regards

Vanya

On Tue, Jun 7, 2016 at 7:26 AM, Lars Helge Øverland lars@dhis2.org wrote:

Hi Vanya,

thanks for taking the time to document this.

–
With Regards
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Just some suggestions for your question on where to put what:

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

Developer guide (API docs)

  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy

I suggest a new chapter in the user manual called “Metadata synchronization” for these.

http://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

Add to settings chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch23.html

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

Add to data administration chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch22.html

It would be good if you could help us get started.

regards,

Lars

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Lars Helge Øverland

Lead developer, DHIS 2

University of Oslo

Skype: larshelgeoverland

lars@dhis2.org

http://www.dhis2.org

–

8

Yes Morten that was specific to my machine. The issue is identified and we are able to build the package successfully.

···

On Mon, Jun 27, 2016 at 12:44 PM, Morten Olav Hansen morten@dhis2.org wrote:

Hi

I’m not aware of any extra steps needed, I just built it fine here locally… (mvn clean package), could be something local on your laptop? I see no complaints from our build server either

–

Morten Olav Hansen

Senior Engineer, DHIS 2

University of Oslo

http://www.dhis2.org

On Mon, Jun 27, 2016 at 1:59 PM, Aamer Mohammed aamerm@thoughtworks.com wrote:

Hi

We have forked dhis2-docs repo to get started with the documentation for the new features. However when we try to build the just cloned repo with apache maven as mentioned in http://dhis2.github.io/dhis2-docs/2.22/en/implementer/html/apas09.html

we are getting below error

[ERROR] Failed to execute goal com.agilejava.docbkx:docbkx-maven-plugin:2.0.17:generate-html (chunked-html-docs-implementer) on project dhis-documentation-docbook: Failed to transform dhis2_implementation_guide_en.xml. org.xml.sax.SAXParseException; systemId: file:///Users/aamerm/Documents/oca/dhis2docs/dhis2-docs/src/docbkx/en/dhis2_implementation_guide_en.xml; lineNumber: 35; columnNumber: 68; An ‘include’ failed, and no ‘fallback’ element was found. → [Help 1]

Are there any other steps apart from the ones mentioned in readme. Please suggest.

Thanks

Aamer.

On Tue, Jun 7, 2016 at 10:48 AM, Vanya Seth vanyas@thoughtworks.com wrote:

Thanks for the information Lars.

Regards

Vanya

On Tue, Jun 7, 2016 at 7:26 AM, Lars Helge Øverland lars@dhis2.org wrote:

Hi Vanya,

thanks for taking the time to document this.

–
With Regards
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Just some suggestions for your question on where to put what:

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

Developer guide (API docs)

  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy

I suggest a new chapter in the user manual called “Metadata synchronization” for these.

http://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

Add to settings chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch23.html

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

Add to data administration chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch22.html

It would be good if you could help us get started.

regards,

Lars

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Lars Helge Øverland

Lead developer, DHIS 2

University of Oslo

Skype: larshelgeoverland

lars@dhis2.org

http://www.dhis2.org

–

9

Ok, good :slight_smile:

···

On Mon, Jun 27, 2016 at 4:13 PM, Aamer Mohammed aamerm@thoughtworks.com wrote:

Yes Morten that was specific to my machine. The issue is identified and we are able to build the package successfully.

–

Morten Olav Hansen

Senior Engineer, DHIS 2

University of Oslo

http://www.dhis2.org

On Mon, Jun 27, 2016 at 12:44 PM, Morten Olav Hansen morten@dhis2.org wrote:

Hi

I’m not aware of any extra steps needed, I just built it fine here locally… (mvn clean package), could be something local on your laptop? I see no complaints from our build server either

–

Morten Olav Hansen

Senior Engineer, DHIS 2

University of Oslo

http://www.dhis2.org

On Mon, Jun 27, 2016 at 1:59 PM, Aamer Mohammed aamerm@thoughtworks.com wrote:

Hi

We have forked dhis2-docs repo to get started with the documentation for the new features. However when we try to build the just cloned repo with apache maven as mentioned in http://dhis2.github.io/dhis2-docs/2.22/en/implementer/html/apas09.html

we are getting below error

[ERROR] Failed to execute goal com.agilejava.docbkx:docbkx-maven-plugin:2.0.17:generate-html (chunked-html-docs-implementer) on project dhis-documentation-docbook: Failed to transform dhis2_implementation_guide_en.xml. org.xml.sax.SAXParseException; systemId: file:///Users/aamerm/Documents/oca/dhis2docs/dhis2-docs/src/docbkx/en/dhis2_implementation_guide_en.xml; lineNumber: 35; columnNumber: 68; An ‘include’ failed, and no ‘fallback’ element was found. → [Help 1]

Are there any other steps apart from the ones mentioned in readme. Please suggest.

Thanks

Aamer.

On Tue, Jun 7, 2016 at 10:48 AM, Vanya Seth vanyas@thoughtworks.com wrote:

Thanks for the information Lars.

Regards

Vanya

On Tue, Jun 7, 2016 at 7:26 AM, Lars Helge Øverland lars@dhis2.org wrote:

Hi Vanya,

thanks for taking the time to document this.

–
With Regards
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Just some suggestions for your question on where to put what:

As we understand that there are 3 manuals

  • Developer guide
  • User guide
  • Implementor guide

When we do the documentation are we targeting all these guides?

Some key aspects that we believe are documentation worthy are:

  • The new API 's (versioning and sync).

Developer guide (API docs)

  • The new task (Metadata sync task)
  • Metadata Versioning and Metadata Sync as a concept.
  • Best practices around the Metadata versioning setup.
  • Optimization of the initial setup of new field instances given the central-field deployment strategy

I suggest a new chapter in the user manual called “Metadata synchronization” for these.

http://dhis2.github.io/dhis2-docs/master/en/user/html/dhis2_user_manual_en.html

  • The changes to the existing “Settings” app [which is pretty much part of setting up the Synchronization settings and the ability to create new versions by enabling versioning ]

Add to settings chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch23.html

  • The changes to the “Data Administration” app where we can now also schedule the metadata sync at the time of choice.

Add to data administration chapter in user guide:

http://dhis2.github.io/dhis2-docs/master/en/user/html/ch22.html

It would be good if you could help us get started.

regards,

Lars

–
With Regards

Vanya
ThoughtWorks Technologies

Hyderabad

–Stay Hungry Stay Foolish!!

Lars Helge Øverland

Lead developer, DHIS 2

University of Oslo

Skype: larshelgeoverland

lars@dhis2.org

http://www.dhis2.org

–