Best Practice for location of module documentation

I would like to hear thoughts on best practices for module documentation including setup and configuration, release notes etc.

From what I see the following exist:

  1. Module README.md

  2. Module Wiki - Rest module

  3. OpenMRS Wiki

My thoughts at a high level - not even sure if it’s possible

  1. Have a module specific documentation sub-project named module-docs

  2. Setup tooling such that at release the documentation is generated and updated on OpenMRS wiki pages

Thoughts?

1 Like

I am totally biased towards the README (see Initializer for example). When you head to some repo, you really expect it to be as self contained as possible. Scattering things around is a deterrent in my opinion. Plus, all the advantages of having it Git’d.

Lastly, it becomes an integral part of the committing process (or at least of the release process) to update the docs.

Although it hasn’t been our standard practice up until now, I do like the idea of making the documentation part of the code base.

However, I don’t know if these is the easiest/best place for implementater-level documentation. Are there any best practices for including documentation in the source when you want to make it easily accessible to non-programmers, and you have more documentation than realistically can “fit” in a single README page?

Take care, Mark

@mogoodrich I was actually thinking of leveraging gitbook publishing with Markdown in a docs sub-module which would allow to have more pages that are easily navigable - which extends the single readme which now becomes a gateway into the documentation.

I don’t know anything about gitbook, but from your short description sounds like what we are looking for.

Take care, Mark

@mogoodrich GitBook is already being used at New home for the OpenMRS Guide and Developer Manual and OpenMRS Android Client User Guide