I accidentally a word.


Open Help 2013 Wrap Up

As per my previous post over the weekend I had the pleasure of attending the first two days of the Open Help conference in Cincinnati, Ohio. Thanks again to the conference sponsors Mozilla, Github, WordPress, and – my own employer – Red Hat as well as Shaun McCance for his tireless organization. Rather than provide a brain dump quite as detailed as I did for day one I am going to provide a full wrap up in this post covering both days I was in attendance.


Siobhan McKeown has provided some excellent notes from the formal presentation track so I will provide those links here before diving into my own takeaways and key themes:

In addition to the above:

  • Siko Bouterse and Jake Orlowitz from the Wikimedia Foundation presented the Wikipedia Teahouse, an effort to create a more welcoming space for new editors with a view to ultimately “building better wikipedians”.
  • Warren Block presented on the current documentation processes, and improvement focuses, of the FreeBSD project which turns 20 this year.

Time was also provided for some more informal demonstrations and discussions, which I will get to in a moment.


My key takeaways and thoughts from the presentations were:

  • StackExchange style question and answer sites continue to be a very hot topic:
    • Whether you like it or not, your product/project has a presence on a StackExchange site or clone. You can choose not to engage, but you have to be happy with the advice that leads to.
    • StackExchange style sites do not replace formal documentation but provide an on-ramp to it which also happens to have a very high search engine ranking. Whenever possible cross link the formal documentation in your answers.
    • When launching a StackExchange style site it’s crucial to have early engagement, preferably from intermediate users. Those who are not expert enough they don’t have any questions, but also not too “fresh” to be able to answer any. This is a key issue I see with ask.fedoraproject.org and ask.openstack.org where the lack of that kind of engagement push has (in my opinion) resulted in a trickle of questions, many of which either go unanswered or don’t receive up/down votes.
  • Metrics to die for:
    • The majority of the presentations were able to cite very solid metrics illustrating how site or program usage changed in reaction to various changes in particular breaking down how content is being accessed and used (not just when and from where as has traditionally been the case). The presentations of Michael Verdi (Mozilla) and Jorge Castro (Canonical) were particularly convincing in this regard.
    • A lot of the documentation demonstrated was of the troubleshooting/knowledge base variety – short, sharp articles. Usually these had at least a “like” or “I found this helpful button”, if not comments. Integration of comment systems like Disqus in more formal documentation is also getting very common. Consensus was that if you do this you need someone dedicated to handle curating the comments (in particular turning those that are appropriate into bugs) and getting rid of spam, but that it was worth it to remove the barriers for users wanting to report documentation issues who will jump through very few hoops.
  • On screen tutorials really taking off:
    • Several of the presentations included guided tutorials that interacted with the elements of the UI itself to walk users through the steps rather than defer to an external guide. This functionality was really elegantly implemented – would love to see something like this in some of the web-based interfaces I frequent like the oVirt’s Administration Portal and OpenStack’s Horizon.
    • Technologies used included Walkthrough and Selenium.
  • Communities often unwilling to delete or archive old content, regardless of current correctness.
    • Presenting a large maintenance burden for several of the groups present.
  • There is just some outright cool stuff happening in user help and documentation, at some level it was simply reinvigorating to get to the fire hose and “fill up” on ideas.


  • Jorge Castro from Canonical came back to demonstrate discourse which is an effort by the same people behind StackExchange to revolutionize the web forum. I was already aware of it but none the less Jorge is an entertaining and energizing speaker so it was interesting to get his first impressions. On face value it certainly seems like a lot of thought and effort has been put into it to make it an immediate improvement on the existing options for forum software, and it’s all delicious open source.
  • Shaun McCance demoed screencasts with translatable subtitles, sweet! The screencasts themselves were in WebM format with the subtitles, and timing, defined in the TTML format for defining timed text (a W3C standard). This was very, very, cool – I want the ability to do this yesterday. He also showed off some of the new “getting started” videos that appear in more recent versions of GNOME (I had seen this in Fedora 19 so I assume GNOME 3.8) which were based on simple SVG wireframe style images being combined using blender.
  • This led on to Michael Verdi from Mozilla providing a brief demostration of recording screencasts and user acceptance tests with ScreenFlow, looks like a very cool way to quickly put high quality videos together but unfortunately Mac only.
  • I did a brief introduction to and demonstration of PressGang CCMS and Press Star. I attempted to provide a contrast to Lana Brindley’s talk “Open Source in Four Easy Steps (and one slightly more difficult one)” given at the same conference in 2011 by discussing where we were at in our topic-based authoring journey then, where we are at now, and providing a quick demo creating a new content specification (topic map), creating a topic, tagging the topic and editing it. There were some gremlins (live demos huh) but overall this was well received. Lee Hunter’s talk earlier in the day about turning Drupal into a fully fledged CCMS for technical authoring shows that there is definitely interest out there in taking this next step for FOSS documentation.
  • Lee returned quickly to show off xmled, an in browser editor for DITA. It takes a single pane WYSIWYG (sort of) approach instead of the two pane view with XML editor on one side and rendering on the other.

Hopefully I didn’t miss anyone! I flew out on the Sunday evening, leaving others to begin their book sprints for the remaining two days. Shaun’s short and sweet demo of the subtitled screencasts was definitely a highlight for me but all of the presentations over the weekend were of a very high quality and provided a lot of food for thought. Will definitely be looking to attend this again in future and can highly recommend to others!

Social Media




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