Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
I think they all should be moved over, but we should keep short chapters in the user manual explaining their purpose and a few examples, with pointers to the new dev manual for further detail
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
This a most welcome development which will definitely revolutionize Web API driven web development. One issue which I recommend you to note would be:
There have been so many changes in the Web API from 2.14 to 2.16 from the perspective of building apps on top of dhis2 such that there is always the risk of apps breaking when the underlying dhis2 backend is upgraded. So not sure how easy it will be to deal with such challenges in the upcoming manual. Maybe some tips and tricks (relevant to the dhis2 version in use) will suffice.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
Sounds like a great idea. The user manual is rather large, and I agree that it would be nice to make a manual more focused on people who are more focused on the programming side of things.
“Programming” here is interpreted rather broadly, everything from using curl with the API through integration with other software, app development, and even core development. I agree that a good dividing place is to put in the user manual everything that happens through the UI, and the other things in the programming manual.
I also like Knut’s idea of keeping some information in the user manual, so that users know there is a next level. Perhaps this could evolve into a “programming” chapter, or maybe a less scary name “Customizing DHIS2”. This chapter would give an overview of the programming manual content, and the user is referred to the programming manual for more information. Then a technical user who wants more than they can get through the UI can be directed to the programming manual. And a non-technical user who wants more than they can get through the UI can ask their technical staff to consult the programming manual and advise them.
Cheers,
Jim
···
On Thu, Aug 21, 2014 at 8:25 AM, Farai Mutero fmutero@gmail.com wrote:
Hi Jason
This a most welcome development which will definitely revolutionize Web API driven web development. One issue which I recommend you to note would be:
There have been so many changes in the Web API from 2.14 to 2.16 from the perspective of building apps on top of dhis2 such that there is always the risk of apps breaking when the underlying dhis2 backend is upgraded. So not sure how easy it will be to deal with such challenges in the upcoming manual. Maybe some tips and tricks (relevant to the dhis2 version in use) will suffice.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
@Bob, I think the developers manual (as noted by others) should cover both development of DHIS2 (Java) as well as all the stuff currently covered in the API and Apps chapter. The “technical architecture” chapter provides some clues, but no real detail in terms of how people who know Java (i.e. external developers outside of the DHIS2 core development team) can get started to customize DHIS2. Of course, there are many other issues which complicate this, such as the lack of clear guidelines on how patches/contributions will be handled. I think we need a lot more information here, and something which I will work with the core team on in the near future.
@Farai, I agree, we do not do a good job of versioning of the documents. We should be able to do a better job of this, as all of the documents are also versioned to a specific version of DHIS2. I will take note of this, and see if we can come up with a better solution. During the workshop last week in Oslo, versioning of the API was also discussed, and this is something which devs using the API should anticipate will be implemented at some point.
@Jim, I like the idea of splitting it at the UI. Seems to make a lot of sense, as most “users” interact only with DHIS2 this way.
Any other comments/objections before I start to take things apart?
Sounds like a great idea. The user manual is rather large, and I agree that it would be nice to make a manual more focused on people who are more focused on the programming side of things.
“Programming” here is interpreted rather broadly, everything from using curl with the API through integration with other software, app development, and even core development. I agree that a good dividing place is to put in the user manual everything that happens through the UI, and the other things in the programming manual.
I also like Knut’s idea of keeping some information in the user manual, so that users know there is a next level. Perhaps this could evolve into a “programming” chapter, or maybe a less scary name “Customizing DHIS2”. This chapter would give an overview of the programming manual content, and the user is referred to the programming manual for more information. Then a technical user who wants more than they can get through the UI can be directed to the programming manual. And a non-technical user who wants more than they can get through the UI can ask their technical staff to consult the programming manual and advise them.
Cheers,
Jim
On Thu, Aug 21, 2014 at 8:25 AM, Farai Mutero fmutero@gmail.com wrote:
Hi Jason
This a most welcome development which will definitely revolutionize Web API driven web development. One issue which I recommend you to note would be:
There have been so many changes in the Web API from 2.14 to 2.16 from the perspective of building apps on top of dhis2 such that there is always the risk of apps breaking when the underlying dhis2 backend is upgraded. So not sure how easy it will be to deal with such challenges in the upcoming manual. Maybe some tips and tricks (relevant to the dhis2 version in use) will suffice.
Hi there. Based on some good feedback last week during the Oslo DHIS2 Academy, I have made a first cut of a developer manual. As I see it, this basically involves slicing out all of the stuff really aimed more at developers (and in some cases implementers) and less so, users. The chapter on the WebAPI is being constantly expanded by the core developers, but in many cases, far exceeds the level of information required by most users. Some of the developers/implementers which I spoke with last week wanted more information in the developers manual. So, I think moving the really technical stuff to a dedicated developer manual would be a good idea, and allow even more detailed technical stuff to be written, without necessarily addressing the needs of the users.
I have , for the time being, left the sections (Technical architecture, Web API, Apps, and the appendix on R) in the main manual, but I think (depending on feedback from the community) that we can slice these out of the main user manual, and put them in a dedicated developer document.
