What's up Doc(umentation)?

OPW with OpenMRS Summer 2013- documentation style

Month: August, 2013

Update from the World of Docs

A lot has happened these past two weeks, most of it revolving around opening up my current work to the OpenMRS community for review, feedback and critique. I also met Ellen Ball, one of my mentors! It was great to see her in person and put a face to all of our email/IM/video/voice conversations.

I finished the Style Guide- it includes a section for conceptual writing tips (such as layout, style, etc) and a section for technical writing tips (spelling, punctuation, etc). A lot of the information for this guide came from reading through style guides for other organizations (especially GNOME and Atlaissan.) The guide’s rough draft is available here:
https://wiki.openmrs.org/display/~evoeges/Documentation+Style+Guide.
It’s ready and waiting for feedback!

I also updated the module documentation template, adding a few more sections (Ownership- who can be contacted to discuss the module? FAQ, and where to direct further questions) and altering a few others (the beginner explanation is now ‘How it Works’ and the advanced explanation is now ‘Technical Explanation’). A lot of great feedback has been coming in, so I’ll be updating it again this week and tweaking it based on suggestions.

I’m still sorting through the current documentation and labelling based on the level of work each page needs. Labels for pages are Red, Yellow and Green and pages can be aggregated based on their labels for easy organization.
https://wiki.openmrs.org/display/~evoeges/Sorting+Current+Documentation.
I’m also trying to add comments to pages to explain what I think most needs to be improved.

Screenshot from 2013-08-18 15:31:45

Upcoming: the first implementation of the Documentation Template! As I sort through pages, I’m on the lookout for a good page(s) to update to the Template and use as example documentation pages.

GUADEC 2013: Learning from Another FLOSS Project

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:

wordcloud1

The font and colors weren’t cutting it. A few more iterations later and I finally settled on this one:

openmrsroughdraftcropped
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.]

For example:

  • 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.