This week is the GNOME User And Developer European Conference [GUADEC], an annual conference held (this year) in Brno, Czech Republic. I’m here meeting the OPW organizers (the Outreach Program for Women is part of the GNOME Foundation) and other interns, and attending some fantasically informative and interesting talks.
I’ve been attending talks that are oriented for new developers (“Put Your GNOME foot forward”; “Newcomer’s Workshop”, “FLOSS Community Outreaches”) to learn about how another FLOSS project handles outreach and newcomers (and learning how to make contributions to GNOME myself!). A lot of great tips and advice that are more than applicable to OpenMRS have surfaced, and many things that can be incorporated into the New Developer Guide, which I’ll be revamping in the coming weeks.
- “start with your favourite applications, start small.” For OpenMRS, start with your favourite modules! Start simple.
- “read wiki pages and documentation.” Maybe even contribute to the wiki pages and documentation, as a starting point to learn about OpenMRS and join the community.
- “keep track of things for yourself; make a checklist, keep a blog, update your personal wiki page.” Keeping your personal wiki updated is a great way to keep everyone in the community up to date on what you’re doing
- “work with the community, not against it.”
I’m also looking forward to attending talks specific to documentation (tomorrow, “Documentation: State of the Union”) and a talk specifically about OPW.
Apart from that, I’ve been continuing my work from last week and have my first simple infographic. I decided to go with something that wouldn’t be too complex, but could incorporate much of what I’ve learned from interviews. I settled on a wordcloud format to start. I used a couple of different programs (Wordle, Tagxedo) and finally settled on Tagul. I made the wordcloud by reading through the transcripts of my interviews, picking out the key ideas, words and phrases. A lot of people mentioned the same, or highly similar things, so I kept a tally of frequent mentions. I’ve tried to use exact wording from my interviews, but at times I’ve shortened phrases to a word that summarizes them without losing content. (For example, if an interviewee suggested ‘make sure information is specific’, I’ve shortened it simply to ‘specificity’.) I made a couple of different clouds, with emphasis on different things, and played around with coloring and fonts. Here’s an early one:
The font and colors weren’t cutting it. A few more iterations later and I finally settled on this one:
As an educational tool, it’s easy to glance at and take key concepts from. It’s ideally accompanied by a short glossary explaining each of the words and phrases. [I decided to leave out the watermark for spacing reasons, in keeping with the guidelines for the logo.]
- basics: make sure that documentation is not wholly technical. For new users, it’s important that the basics be explained along with the technical complexities. This makes things much easier to understand and less overwhelming.
- organization: when writing documentation, make sure that it has a clear organization that will be easy to follow for readers. The best way to do this is to follow the Documentation Template, which has pre-established divisions for a logical layout. Of course, the template is not rigid and every aspect is not applicable for all documentation. Just be sure that there is a clear flow of ideas, allow for headings and divisions to separate information so that a reader can easily see the layout of the documentation and find their information.
- simplicity: OpenMRS is used worldwide, and often English is not the first language of users, developers and implementors. Using language that is not overly complicated removes barriers to understanding, and enhances clarity.
- specificity: Especially when writing developer documentation, reference classes, functions and modules that are necessary for understanding by name, rather than vague mention.
- update: The importance of keeping pages up to date with correct information cannot be overstated, especially in a project where things are constantly changing and being modified and new things are being added.
I’m working on writing up definitions to the rest of the tags in the word cloud, so a short draft of the accompanying glossary will be up soon.
Hopefully, it’s something that will be a useful introduction to OpenMRS documentation and help people think about the key concepts and ideas behind writing module documentation, along with the framework. It also serves as a visual representation of the work and research I’ve been doing that’s hopefully a little more interesting than just another written report.