A pattern library for user assistance

Rob Houser is working on a Pattern Library for User Assistance (UA): At WritersUA, he proposed to collect examples for patterns in (embedded) user assistance to help teams and managers with whom UA professionals collaborate to better understand the benefits and value of UA. Among UA experts, it can help to establish and exchange standards by deducing principles and concepts from them.

Rob Houser at WritersUA

UA patterns can be organized by the task they support, whether it is helping users to get started in a new application or task or to assist them in the correction of errors. A fairly well-known example of the first case is Internet Explorer’s help text that appears when you open a new, empty tab. Such a pattern can support users in:

• Understanding conceptual information what has happened, what options the user has, when to use this function and why.
• Make decisions by providing context, reference information about rules as well as hints for best practices.
• Solve problems by describing the problem, showing how to fix it, give background information, if available, and show how to avoid the problem in the future, if possible.

Such a library will be really helpful, because it will fill the gap between very formalized, but abstract topic types (concept, task, reference) as DITA models them and the wide variety of UA that’s actually “out there”.

With a community effort of collecting and annotating patterns, such a library can be a qualified, curated collection of best practices in UA that can help tech writers write better help faster by following tried and proven examples.

So I agree with Rob’s approach and think such a pattern library would benefit a lot of people. Personally, I can’t wait to start and deduce the underlying principles and concepts of sucessful UA patterns. While examples can be instructive, I prefer to work in more abstract terms. This would also square better with the general approach in UA to separate content from style. After all it shouldn’t matter whether UA is provided in the actual user interface (where real estate is often scarce, esp. in mobile applications), in a tooltip or in a separate window.

Chuck Martin also blogged about this interesting session. I’ll be following Rob’s efforts and report when there’s new developments.

Your turn

Is this something that would help you as a tech writer or UA professional? Would it be instructive to have annotated examples of best practices in user assistance? Please leave a comment.

Advertisement

15 things I learned at WritersUA

WritersUA brought many small epiphanies, quick bursts of insight, that I’d like to share. From each session I attended, I present a tasty morsel that whets the appetite, that’s meant to be shared. It also gives you an idea of the breadth – and occasional overload – of information at the conference. (Of course, the sessions also offered much more substantial lessons than these, but they will take me a little longer to digest.)

But for now and as a tribute to going dinner with the conference crowd to a restaurant called “Sevilla”, here are:

Tech-Comm Tapas in Long Beach

• Much of “CSI: Miami” was or is apparently filmed in Long Beach, from Let’s Look in the Mirror and See What We See with Matthew Ellison, Tony Self, and Joe Welinske.
• A pattern library for user assistance can help to disseminate best practices and establish standards for user assistance design, from A Pattern Library for User Assistance with Rob Houser.
• To bridge cultural differences in a global, distributed team, mutual trust and respect beat everything else, from Global UA Guidelines and Requirements with Pam Noreault.
• Documentation and training may share contents, their goals are at odds: Documentation constitutes an external knowledge repository, while training aims to build an internal knowledge repository. That makes it a little harder to reuse contents, from Opportunities for Reuse between UA and Training with Linda Urban.
• When switching to a new tool, get every writer a license as early as possible, so they have plenty of time to get used to it and play around, from Double Scoop Case Studies about MadCap Flare, with Denise Kadilak.
• As one of their single-sourcing methods, Flare supports global project linking. This allows you to share and inherit just about any file across projects, including topics, from Double Scoop Case Studies about MadCap Flare, with Patrick Calnan.
• Single sourcing documentation for multiple (similar) products and content reuse can reduce content by around 30% and reduce yearly efforts by almost 50%, from Double Scoop Case Studies about single sourcing, with Deb Woodcroft.
• The paid version of SharePoint includes a translation management feature which automatically creates copies for each language and lets you assign tasks to translators, from A Realistic Approach to Content Management with SharePoint with Dan Beall.
• The 7+/-2 rule was never meant for the optimum number of steps in a procedure. It comes from a study about how many random things people can remember for a short time. Instead, the optimum number of steps is (usually) less than 10, but for different reasons, from Help Procedures That Work with Leah Guren.
• Ensuring accessibility of web sites and documentation for people whose physical and/or mental capacities are restricted is not an issue that affects “them”, it affects us, specifically each one of us who is aging, from Making Your UA Accessible to All by Shawn Henry.
• If you create an operating system, make sure the name doesn’t undermine your efforts: Windows CE (“wince”) and OS/2 (“OS half”) will come back to haunt you after years when they appear in The Geek Trivia Quiz Show.
• When you create podcasts, ensure you make your audience part of the conversation – talk with them, not to them, from The Art of Podcasting with Omaha Sternberg.
• Trying to create PDFs from DITA with open source tools may make you look less sophisticated than you are, from What They Won’t Tell You About DITA with Alan Houser.
• During a phone interview with subject-matter experts, simultaneous chat is the perfect way to keep and verify notes and to add screenshots on the fly, from Strategies for Working with Subject Matter Experts with Susan Becker.
• You can use “elements of surprise and fear” (obvious Monty Python reference that wasn’t in the session) to remember where you put your keys: Wherever you put them, imagine that place explode as the keys hit, Tickling the Brain: Sharing Ideas in Memorable Ways with Adam Rubin.

Thanks for the insights and the memories, everyone!

If you’ve been to WritersUA, feel free to share your favorite tapas-like takeaway in the comments.

Top 5 things I like about WritersUA

WritersUA is a very stimulating and inspiring conference! This year’s 19th annual conference draws 360 attendees (speakers included) which makes it the largest tech comm conference I’ve attended so far. Kudos and compliments to Joe Welinske and his whole team who simply “get it right”.

Here are the top 5 things I like about WritersUA:

1. Great program, good pace

An online community on the conference web site allows attendees to connect as much or as little before the conference as they like. The program is paced very well: At 60 minutes, sessions are long enough to be thorough and leave time for questions and discussions. 20-minute breaks between sessions allow for several contacts with attendees and/or exhibitors.

2. Proceedings are available before hand

At first, I was overwhelmed by the package I received at registration, but it makes sense: Looking through the slides allows you to make the best possible decision which session to attend. Even if several presenters have edited their slides after submitting them for print, but the earlier versions are always a good, reliable indication. Initially, I had selected sessions by my general interest in the topics. After reviewing the slides, I changed my schedule for Monday completely. One session looked more basic than I had expected, and the slides are so comprehensive I couldn’t imagine I would miss much (and from what I heard from attendees I didn’t).

3. Sessions that are worth attending – in person

I got the most out of sessions that offered constructive discussions in addition to mere presentations:

• Rob Houser presented a “community-works-in-progress”, a Pattern Library for User Assistance, where we discussed whether this was something worth having, whether we could imagine contributing to it and how to best go about it. (For more information, follow the link above, see Chuck Martin’s write-up or watch this space for a more elaborate review.)
• Linda Urban described and analyzed her experiences with Opportunities for Reuse Between User Assistance and Training and invited a discussion which was very enlightening: Even between two such closely related domains, different cultures, organization, budgets and deliverables make it difficult to break down the silos and to collaborate successfully.

4. Comprehensive look at help authoring tools

WritersUA offers a unique combination of first- and second-hand experiences to compare tools in depth.

The exhibition area at WritersUA

• In the exhibition area, most of the relevant vendors are present among the 14 exhibitors and more than willing to present their products in the best possible light.
• In a lab, attendees have access to most of the relevant tools at workstations. You can just play around with them or visit at a time when a vendor is at hand to ask questions (though these are not presentations).
• And during the meals and breaks, you can ask other attendees about their experiences with the tools.

5. Great gathering of passionate, fun tech writers

As early as Saturday afternoon, I met friends from previous conferences and people who’s writing, blogs or tweets I’ve seen online. The various networking opportunities make it easy and fun to strike up a conversation, trade travel stories, share frustrations about clueless managers or absurd processes or quote obscure Doors’ songs.

– So far, WritersUA has been a great example of my Top 5 reasons to attend a tech comm conference. If you’re attending WritersUA or have attended a tech comm conference in the past, feel free to share what you liked best about them in the comments.