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:
Module Wiki - Rest module
My thoughts at a high level - not even sure if it’s possible
Have a module specific documentation sub-project named module-docs
Setup tooling such that at release the documentation is generated and updated on OpenMRS wiki pages
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?
@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.