OpenHelp Trip Report: Warren Block

Warren Block of the documentation team recently submitted his trip report for the OpenHelp Documentation Conference:

The Open Help Conference was held in Newport, Kentucky, just across the river from Cincinnati, Ohio.  Shaun McCance, the GNOME documentation team’s “Fearless Leader”, organized the conference to bring together open source documentation groups.  Dru Lavigne of PC-BSD asked me earlier this year to attend, and the FreeBSD Foundation graciously sponsored the trip.  Conference attendance was rather small, but as the conference went on, it turned out that a smaller group allowed for different, more personal discussions which I really enjoyed.

Several of the attendees arrived two days early to work on an open source style guide.  Trying to start a project from scratch turns out to be surprisingly difficult.  We spent a great deal of time talking about the issues that affect documentation, and particularly open source documentation.  Content issues like tense, passive or active voice, weasel words like “should”, compound words, and translation all came up. How to organize such a document is a huge question also. Then there were project issues, like what license to use, where to host, what type of markup language to use, even what to call the document.  The nice thing about existing projects is that while you may not be particularly happy with the rules or decisions, you are at least freed from making all those decisions to work on actual content.  In the end, an archive was created on gitorious with a collection of some of the basic ideas.

The conference itself began with Florian Nadge of SUSE and his talk, Writing for Translation.  As an American, I can barely speak English, yet there was a lot of crossover between the concepts of writing to make translation easy, and writing for clarity.  Many of the concepts are the same: keeping sentences short, not combining multiple ideas into one sentence, avoiding things that are difficult to translate like humor and jargon.  Another interesting point was that translation teams are often the first people in a country to be introduced to software, and the same people can become valued contributors.  Several recommendations that we should add to the FreeBSD documentation Primer include active voice, consistent words for the same meaning, and keeping sentences to less than 23 words.

I followed with my presentation on automated documentation proofreading with igor (textproc/igor).  The concept of making documentation easier to write by having the computer proofread everything that can be automated is a surprising idea to some people.  As usual, people were fascinated with features that seemed simple to me, and vice versa.  This is one of the best reasons for these conferences: the cross-pollination of ideas.

Next up were a series of shorter talks on tools.  Janet Swisher of Mozilla gave a demonstration of Popcorn Maker, an HTML5 Javascript library from http://popcornjs.org/ that allows integrating video into documentation.  The really clever part of this is that it can use existing video without any changes, tying a particular point in a video to a link in documentation, or the other way around.

Anne Gentle of OpenStack talked about Clouddocs Maven, a web-based documentation system.  Shaun McCance spoke on ITS Tool, a program that assists in translating XML with PO files.  It is in FreeBSD ports as textproc/itstool.

The second day of the conference had more usable information.  Jean Weber of the LibreOffice documentation team discussed how they produce documentation with a very small team of diverse contributors.  Florian Nadge spoke about Publican, the Red Hat DocBook XML toolchain.

Shaun McCance gave another presentation, this time on making documentation accessible for people with differing physical abilities. As with the other talks, there were surprising crossovers.  For instance, help systems that require a mouse are unusable for people with limited movement, but also on a factory floor where there is no place to put a mouse.  Audio and video help face similar restrictions.

After the presentations, the group had a series of far-ranging talks covering such subjects as how to encourage users to become contributors, how to encourage under-represented groups to become involved in open source, and how to reward and retain contributors.

Finally, on Monday, Dru and I participated in a doc sprint.  We covered use of some of the FreeBSD documentation tools, and took and closed a PR as an example.  She documented–and I occasionally helped identify–the packages needed to run Publican on FreeBSD.  Since then, Steve Wills created a full port, textproc/publican.

The conference was a great experience.  As a side note, Newport and Cincinnati were great towns.

My thanks to Dru Lavigne for inviting me, Shaun McCance for hosting the conference, all the attendees for their participation, and particularly the FreeBSD Foundation for making it possible for me to attend.