At some point we have to consider documentation and training. In fact, we already have faced this in a small way: we have needed text to welcomes new participants to this forum and to define terms of service, governance, etc. The need for documentation and training will spike as we create code and start real-life projects.
We can draw on a lot of existing material about OpenMRS, but it has weaknesses that I’m told are freely acknowledged (and I reviewed it myself a couple years ago). I’d like to propose a way of thinking about documentation and training that can help us make the most of our limited time and resources.
Please let me know what you think of the approach in this posting and where you’d like the effort to go.
Basic principles
Most users don’t like documentation. They get help through searches that turn up isolated answers to specific questions, often in the form of informal messages on forums like this one, or blog postings. Both quickly get out-dated. New people also ask questions on forums–which generate more informal postings.
We need to make extensive use of the informal postings generated out of spontaneous generosity by the community, and enhance them to make them more long-lived and valuable. We also must consider all available media, such as video.
Search
The first task is to make search on our forums as powerful as we can. Smart searches, such as ones that recognize synonyms, would be wonderful, but these require complex tasks such as defining ontologies. If we can just get a search that ranks postings well by relevance and (using the “heart” or “like” feature) quality, we’ll be off to a good start.
Upgrading postings
Considering that the easiest way to get content is through responses to questions or spontaneously written blog postings, we should find the ones that the community seems to consider valuable (perhaps through “likes” and perhaps through human selection) and turn them into something more permanent. The difference between most informal postings and documentation of lasting value include:
- The documentation is promptly updated when needed, and errors are promptly corrected when discovered. (Of course, this is an ideal, often unfulfilled.
- Informal postings assume that readers know a lot of context related to the time and topic they cover: readers should know the particular software module and version being discussed, what the current problems are, and what the goals are. All of this context may be lacking when a forum member finds the posting months later, so it should be explicitly added to form lasting documentation.
- Documentation is usually in a known, trusted place such as a wiki or manual. Because it’s actively maintained and officially blessed, documentation is trusted more.
I’ve explored some of these principles in an old article.
How can we upgrade the most useful postings to trustworthy documentation? Someone has to monitor popular postings and contact their authors to recommend upgrading. We also need guidelines in how to upgrade the postings: suggestions for how to identify missing context, for instance.
Keeping documentation up to date is also a much bigger job than throwing in a new option from a menu or command line. Someone who knows how Libre Health is used must regularly go over the documentation to determine where it describes old ways of doing things, and should be changed to describe new ways.
Documentation diversity
Although it’s nice to offer people a manual, perhaps by working through FLOSS Manuals as OpenMRS has done, other ways to invest resources may have bigger pay-offs. As mentioned earlier, many people are too impatient to read the manual. And it’s easier to ask people to upgrade informal postings on blogs or other places than to funnel all their contributions into a central manual or wiki.
We should recognize useful blog postings, videos, and other content from community experts and link to them. We should suggest further readings for people who finish a piece of content. The resulting labyrinth of documentation and training materials may match up better with the way people tend to learn online: they learn a little, try out what they know, and return with more questions.
