This week I’ve been specifically focusing on modules. Modules in OpenMRS are an integral aspect of the software. They are the customize-able ‘add-ons’ that make OpenMRS so well-suited for so many different users. Module documentation has a lot of problems though, as many of the people I’ve interviewed have pointed out. There’s no really clear formula for writing documentation, so two wiki pages on two different modules might be completely different, and as a result, miss on out on important information. Many modules simply aren’t documented, or have such minimal documentation that they’re still exceptionally difficult to parse through. Documentation is vital for functioning modules: not only for downloading and setting up the modules, but for troubleshooting. Modules aren’t just bonus add-ons to OpenMRS; in many situations, modules are integral components in having a useable software.
From the feedback I’ve gotten on module documentation, here are the core ideas:
- accountability: if developers themselves don’t have the time to write documentation on their modules, there needs to be a way to pass responsibility to someone to ensure that the documentation at the very least, exists. This person or people should also be responsible for making sure module documentation stays up-to-date. For example, if someone is discussing a problem with a module or a unique usage of a module on a mailing list, adding that to the module’s wiki page could be enormously helpful for future developers/users/implementors. Rather than digging through old mailing list logs, all of the information pertaining to the module is displayed on the module’s wiki page. One interesting solution would be to keep an updated list of all the module documentation that needs to be written or updated. Anyone new to OpenMRS wishing to make a contribution could access this list. It would be a great way for them to learn about OpenMRS and how it works, and keep documentation updated for the rest of the community.
- beginner/advanced division: one way to keep documentation accessible for OpenMRS newcomers, but also relevant for more advanced developers would be to divide module documentation into beginner and advanced sections. A beginner section might be a conceptual explanation of the module, with some technicality . A more advanced explanation would go into more technical detail (for example, what are the important classes or functions in the code? how do they interact with one another and code from other modules) and include examples of code. A lot of people said that they themselves, or someone they knew, were scared away from OpenMRS at first because of the complexity of much of the documentation. Making information more accessible to newcomers is important to welcome and facilitate their understanding.
- organization: I’ve spoken of it before, but it’s a testament to the importance of clear and logical organization that it keeps coming up in my interviews. One simple way to provide good organization is by adding a table of contents to the beginning of every module page. At a glance, a person can (hopefully) see exactly where the information they’re searching for might be located. Another aspect of organization that I’ve spoken of is consolidation; keeping information more or less in one place. This ties in to the first point of trying to place vital information from the mailing list on the wiki as well.
- visuals: this is a very simple way to add clarity and information to a module page, and many people have attested that visuals are an excellent way to enhance documentation. There’s a range of possibilities for this, from a flow chart that demonstrates what functions call one another to screenshots of the module at work or during the installation phase.
Here’s an outline of what a module documentation framework could be: