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