OpenHelp Trip Report: Warren Block

Open Help is an annual conference for people who write documentation for an open source project. The Foundation sponsored Warren Block from the FreeBSD documentation team to attend this year. He writes:

In June, I attended the Open Help Conference in Cincinnati, Ohio.  Open Help focuses on open source documentation.  Dru Lavigne attended also, and Tom Rhodes arrived for a doc sprint.

This year's attendance was larger than last year, and the changing group dynamics are always interesting.  There was a sign-in session on Friday night at a restaurant in downtown, on Fountain square.

The conference began in earnest on Saturday.  There were some very tantalizing presentations.

Jorge Castro, of Red Hat, spoke about their use of StackExchange for user support.  A key point was that forums and mailing lists are good for discussion, but not very good for user support.  StackExchange is good for user support because discussion is very limited.  The description of how this had improved user support for Red Hat was very interesting.  One problem with using this system for FreeBSD is that it is proprietary.  The StackExchange system is "software as a service", and the software is not open.  For that reason alone, it probably would not fly for FreeBSD.  Still, we could use many of the concepts, like the idea that outdated docs in search results can be worse than no results at all.  That idea was restated by several presenters and attendees.  It comes up a lot.

We have encountered it in FreeBSD, too.  One possible approach I have tried to combat this was about an outdated setting for X11 called AllowEmptyInput.  No amount of corrections seemed to make any difference... until I tried pulling instead of pushing.  Rather than just keep trying to correct the information, I decided I would make it famous.  So I wrote a small article that talked about the problem, the solution, and then ridiculed it.   Surprisingly, that
worked.  However, it does not scale well for all the bad advice out there.

So StackExchange sounds great, but would probably not work for FreeBSD. The very next talk was by Michael Verdi of Mozilla, about the Sumo Project, their homegrown support system.  It shared some of the features of StackExchange, but their Kitsune software is open, and built in Django.  This is something we really should test.  First we need to talk someone into creating a port, but that is a technicality.

Richard Bowen, also of Red Hat, made several interesting points in his presentation, "Listening to your Audience".  One of them was that regardless of your project, your default documentation is StackOverflow. I'm not sure that is true for FreeBSD, but it's an interesting concept. Another idea is that of finding how users got to your documents.  Did they find what they needed?  Or will they go elsewhere?

We also had group discussions and short presentations throughout the day.  Open Help is very informal and freewheeling.

On Sunday, more full presentations were given.  Again, they had areas which directly addressed problems the FreeBSD Documentation Project has encountered.  Lee Hunter spoke about using Drupal for technical communications, and component content management systems.  The idea of being able to write a technical section once, use and reuse it throughout documentation, and being able to revise it in one place really resonated.  For example, we have multiple sections in the Handbook that talk about partitioning hard drives.  They are all different, all incomplete, and difficult to update.  Imagine having one section that is simply included as an object in different parts of the documentation, yet is still only a single piece to maintain.

Jorge Castro gave a quick presentation on discourse.org, a site from one of the StackExchange founders.  It is aimed at reinventing the web forum with some very interesting concepts.

Siko Bouterse and Jake Orlowitz of Wikipedia spoke about their Teahouse project, trying to put the humanity back in technical support.  Their project is kind of the antithesis of StackExchange.  Rather than all-business user support with nothing else, it's a conversational, friendly tone to which moderators must agree beforehand.  Participation by women in this new style of support group is about ten times that of the normal forums, a stunning success.

Peter Coombe, also of Wikipedia, spoke about fixing Wikipedia help pages.  This was yet another presentation that dealt with topics the FreeBSD Documentation Project has encountered.  Help pages become long and complicated, addressing unusual situations that most users will not experience.  It can drive off the people looking for simple help.  I find our Handbook chapters on setting up X11, printing, and wireless networking in that situation.  There is lots of information, but 90% of users are looking for a common answer which can get lost in all the details.  We need to address this with simple quick-start introductions, answering the most common, simple questions first.

Also addressed in this talk was the concept of "sunk costs".  We have seen this, where even though some document is long obsolete, people are reluctant to retire it because of the effort that was put into creating it.  That can be addressed, but it takes understanding.  I think it will help to move old documents into an archive rather than just deleting them.  They will still be available, but also will not be confused with current documents.

Janet Swisher, of Mozilla, spoke about doing doc sprints and book sprints.  Dru has hosted more than a few FreeBSD doc sprints, and they do help.  I feel that in-person attendance gives the best results, and that is difficult for us because most contributors are not employed to work on FreeBSD.

Shaun McCance, organizer of the conference and Gnome documentation team leader, spoke about translations and showed his itstool (in ports as textproc/itstool) for extracting translatable content from XML files, then merging it back in after translation.  Gnome is using this to add subtitles and translated subtitles to help video.

We need to revamp the way we do translations for FreeBSD documentation. Translators already have a difficult task of translating very technical content into a second language--and sometimes a third.  They get no programmatic help to accomplish this, it's all manual.  Gnome has translations into 80 languages.  We do not.  If we can make it easier for translators, we can get more translations, faster, and into new languages.  This really needs to be a high priority, and we need to get a group of translators together to consider newer approaches.

I gave a small presentation about FreeBSD and what types of documentation we produce, and how.  We have some famous successes, like the Handbook and our man pages.  We also have many opportunities for improvement.  Some of those opportunities seem simple when viewed from the outside.  In many cases, difficulties arise due to the sheer length of time that FreeBSD has existed.  FreeBSD predates XML, for instance. But we can improve our documentation, and we can make the process of creating and translating it easier.

On Monday, Dru led a FreeBSD doc sprint.  And she did lead, we did a lot of things that needed to be accomplished to prepare for the upcoming print version of the Handbook.  Tom Rhodes also arrived on Monday, and between the three of us, we finished off more than could be reasonably expected of five.

Monday night, there was a bourbon tasting event, which was unusual and surprisingly educational.

And with that, Open Help 2013 came to a close.  A fun event in a great town with lots of ideas, concrete improvements during the doc sprint, and directions for future improvements to FreeBSD documentation and FreeBSD as a whole.

I want to thank the FreeBSD Foundation for sponsoring my trip to Open Help this year, and Tom Rhodes for his help, and most particularly Dru Lavigne for her help and guidance and refusal to accept excuses.