Documentation: Duplicated description of OpenMRS Developer SDK

Hi,

During my first experiments with OpenMRS I noticed that there are duplicated descriptions for the OpenMRS SDK in the Confluence Wiki#OpenMRS SDK and the Developer Manual#Get Set Up. So I brought up those two questions to @dkayiwa on GitHub and he suggested to raise this discussion here in the forum.

What is the intension behind the information in the Developer Manual? What is the intension behind the information in the Wiki?

Some thoughts about this subject

One option could be to drop the Developer Manual at all, with due respect of the efforts put into it. This could lead to more attention put into the Wiki. Also for the consumers it might be better to have all relevant information at one place.

On the other hand it might be a good idea to keep the Developer Manual. Some time ago I had to train my colleagues writing Selenium tests. I printed out a script with an overview over the most important topics and snippets for the basic testing steps. This was actually used by some of them. Once they are familiar with those guideline were not necessary. The Wiki might be better suited to look things up.

Anyway, though I think it has a better design, the old version of the OpenMRS Developers Guide should be taken off-line some day. Actually the link I stored is to the old version, I just stumbled across the new one when I did an internet search for a description of the options in the Maven dialogs.

How the documentation could be split up

Develop Handbook

Target:

  • Guide for the first contributions to the project

Audience:

  • Beginners (developers completely new to the project)

Contents

  • Maximum size 20-30 pages, for a little printout and semi-professional binding
  • Overview over the system architecture
  • Overview over the project management strategy
  • Getting the development setup up and running
  • Guidance for the first steps
    • Writing and installing a module
    • Extending the core software
    • How to get the changes upstream
  • Where to find further information and get help

Wiki

Target:

  • Reference documentation

Audience:

  • Advanced beginners
  • Advanced developers

Contents

  • Background information about the project. Still better for this would be a little video. A little less time/effort/money consuming solution could be a nice, little brochure which can also be read by non-techies.
  • Learning resources about the technology stack
  • all the rest

I disagree with this. The wiki is more like a reference for every OpenMRS concept. We have wiki pages for almost everything concerning openmrs. For new comers finding different wiki pages when you are just getting started will instead slow them down. That’s why there’s a developers manual. The developers manual is meant to be a gentle introduction to OpenMRS development, it’s not meant to stay with the developer for the rest of their time with OpenMRS. There are a lot of things in the developers manual that have separate wiki pages for each of them but the developers manual kind of introduces them and once the developer has fixed his first issue and build a module(that is acquaint him/herself with openmrs development work flow), they’re expected to start using wiki pages. The developers manual is like a getting started guide and the wiki is like a reference. The issue is that the wiki gets updated more often than the developer manual and sometimes the information in both are not consistent.

I think that’s what the manual is doing already. It just needs updating. Changing the name from developers manual to handbook does not change the concept.[quote=“janux, post:1, topic:12177”] Wiki

Target:

Reference documentation

Audience:

Advanced beginners Advanced developers

Contents

Background information about the project. Still better for this would be a little video. A little less time/effort/money consuming solution could be a nice, little brochure which can also be read by non-techies. Learning resources about the technology stack all the rest [/quote]

I think that’s exactly what the wiki does with exception of videos which you can find a good number of them on the openmrs youtube channel.

The developer manual just needs updating and a way of making sure it’s always in sync with the reference documentation.

1 Like

I like our current developer manual’s being under source control. Though this is not talking about exactly the same, it recommends source control instead of wiki: https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records