I accidentally a word.


Can I get some cheese with that? Open Help Day #1

This weekend I am attending the first two days of the Open Help conference in Cincinnati, Ohio. Open Help brings together leaders in open source documentation and support, as well as people from across the technical communications industry who are interested in community-based help. This year’s event was possible thanks to the contributions of Mozilla, Github, WordPress, and my own employer – Red Hat.

I haven’t had the privilege of attending the event in the previous two years but based on the accounts of those who have attendance was up this year. No doubt this is in part due the tireless efforts of organizer Shaun McCance.

Solving the Q+A conundrum with StackExchange

After a buffet breakfast, normalization of caffeine levels, and a quick welcome from Shaun we launched into the presentation phase of the conference. First up was Jorge Castro from Canonical with his presentation which covered the issues with existing user support systems that led to the creation of the askubuntu StackExchange. Jorge also provided some tips for working within the framework of StackExchange sites (and StackExchange clones, like askbot). Siobhan McKeown has provided her detailed notes from Jorge’s presentation so I am going to concentrate on my own key takeaways:

  • Whether you are cultivating it or not if your FOSS project is mildly well known then it has a presence on a StackExchange site under one tag or another.
  • StackExchange sites in particular (the clones not as much) have very high rankings in search results, treat them not as a replacement for writing good formal documentation but as an on-ramp to it.
  • When launching a StackExchange site, or one based on one of the clones, early engagement is critical.
  • The biggest complaint about StackExchange sites is that they are very sterile. The aggressive design and concentration on getting the best answers means that the sense of being a community takes a hit.

Personally this last point is an area where I see the ask.fedoraproject.org and ask.openstack.org askbot sites as really struggling. Even those users that are engaged enough to earn the required reputation points are not actively involved in using the moderation and editing facilities provided. Consensus in open discussion later in the day was that in the beginning it is desirable to encourage and cultivate a group of early adopters whose understanding of the subject matter is neither that of a beginner, nor of an expert.

Instead the best early adopters are those with an intermediate level of knowledge who both have the need to ask some questions, and the ability to answer others. Not obtaining the correct mix early on results in beginners who are frustrated that their questions never get answered, advanced user who are frustrated with not having questions to answer (or the level of the questions being asked), or worse still – both.

How Mozilla supports users all over the world

Next up was Michael Verdi from Mozilla presenting a discussion of the support they provide for users and how it has, and is, evolving. Michael’s slides are available online and again Siobhan has provided some excellent notes for those who want to dive in. In addition to giving a broad overview of what the Mozilla support organization does and some (very) interesting functionality being integrated into Firefox Michael introduced the kitsune software that powers support.mozilla.org. Some things I found particularly interesting were:

  • The knowledge base detects and reacts to the user-agent of the browser used to access it to ensure that the correct version of each article are displayed.
  • Question and Answer, StackExchange style, functionality is included (anyone noticing a pattern here?).
  • It provides metrics and, based on Michael’s slides, lots of them. I think this is information we are often struggling for in technical documentation. The number of questions we have is basically limitless but we have to be willing and able to collect the data to answer them, or at least ask the NSA to share.
  • A twitter client is included and aggregates Firefox related tweets for members of the “Army of Awesome” to respond to, if appropriate. This was something I found very topical, lately to keep up with user interests for a project I work on I have found myself checking twitter, a forum, an askbot instance, and a mailing list on an almost daily business. It seems to me there is a need to be able to select and aggregate user queries from these diverse sources to get them in front of the right people. This seems to be particularly important when the right people stick primarily to mailing lists which as mentioned earlier in the day are arguably the most convenient form of user support for developers and the least convenient for end users.

Michael finished up by providing some great examples of the way that metrics have fed into efforts to identify the most common pain points for users and the actions taken based on this information to improve the user experience.

One of the other key things I took away from Michael’s talk was that most popular FOSS projects can not scale to support every single user interactively, ideally the majority of users must be consuming information rather than being forces to actively seek it in forums etc. The key is identifying the ways to either improve the content or the software itself to ensure that this is the case. Mozilla seem to be doing a really great job of this and overall I was extremely impressed with what Michael brought to the table today.

Open support: A panel discussion

A panel discussion on open support rounded out the events of the morning. Siko Bouterse, grantmaker at the WikiMedia Foundation and Jeremy Garcia, founder of LinuxQuestions, joined the earlier presenters on the panel. Not surprisingly a lot of the discussion centered around the earlier presentations and the common themes they shared, particularly in relation to Q&A style user help. Jeremy, being the founder of arguably the biggest existing “traditional forum” covering Linux provided an interesting contrast to this discussion. In particular Jeremy cited the feeling of community and friendliness that has been fostered at LinuxQuestions as being a central part of the draw for new users.

As part of the discussion Siko provided a brief introduction to the Wikipedia Teahouse, an effort aimed at improving editor retention by providing a fun area for new users to gain a sense of community and ultimately become “better wikipedians”. At some point in the discussion stripe.com was provided as an example of what happens when a project is launched and the founders make a determined effort to focus on having the best documentation possible.

Listening to your audience

Rich Bowen, who has recently joined Red Hat as a OpenStack Community Liaison, closed out the day. Rich used his past experiences in the Apache, Perl, and PHP communities to deliver a powerful talk  on identifying, listening to, and reacting appropriately to the audience for documentation. His slides are also available online, as is another excellent set of notes written by Siobhan. I would recommend reading both, I am unlikely to do them justice here as a wide range of topics were covered, but my key takeaways were:

  • Comments on documentation often indicate a documentation issue that would otherwise go un-noted. Spam is a huge issue, and curation is important, but the general consensus in the resulting discussion seemed to be that this overhead is preferable to sending users to a system like Bugzilla and losing a huge percentage of those contributions.
  • Some times the right outcome is ultimately just to “fix stuff”. In many ways as an author you are the conduit between the users and the developers. You might have to document a workaround in the short term but where appropriate ensure the need for a better solution is tracked and highlight it to the developers.
  • Whether you like it or not a StackExchange site is the defacto documentation for your project. You can choose not to engage there but have to be comfortable from the advice that results from that decision. At the same time your formal documentation can never be what StackExchange is. The two are in many ways symbiotic, like Jorge earlier in the day Rich encouraged linking your documentation from answers on the StackExchange site and using answers on the site to identify concepts missing from the documentation.
  • Examples in documentation must be correct, fully functional, tested, useful, and annotated. More often than not examples used in documentation fail one or more of these tests.

All in all there was plenty of food for thought in both this and other talks presented today. Without a doubt though the theme throughout were that StackExchange style Q&A sites are here to stay and that metrics are increasingly playing a huge role in driving the user support choices being made by FOSS projects.

Twitter Feed



Comments are closed.