What should be documented where?

Hello, I’m working with a group of new developers, and we were planning to help update documentation in the wiki and the README for a few modules. Some of the modules we looked at don’t have a README at all, and we were planning to create one.

We were wondering if there is an expectation that certain information is documented in the wiki and certain information is documented in the README. We want to respect any guidelines on what is documented where in OpenMRS. Can we provided detailed new developer instructions in a README, or should that information only be found in the wiki?

1 Like

Thanks for the offer of help. I would suggest following the prevailing convention on github of putting the basics to use the module in its README.md (overview/purpose, requirements, installation, basic configuration/settings, and basic troubleshooting tips if applicable). Every module should have a LICENSE (usually our MPL 2 + HD, but could be another OSI license if the module author wanted) and a CONTRIBUTING.md instructing people how to make contributions.

In nearly all cases, we avoid using the wiki feature on github and favor using the community wiki instead. So, I would create wiki pages for a module when you want to provide documentation beyond the basic readme. For example, a user guide, step by step instructions, detailed release notes, road map, etc.

We have definitely followed the README approach for the obvious reasons of documentation versioning and ease of linking the code base with its documentation. See the Initializer module as an example.

Also I love Markdown and I can’t figure out why Atlassian never adopted it (and I really dislike that they didn’t).

But so to not confuse you in regards to @burke’s guidelines, at the very least the README should clearly point to where the documentation is on the wiki.