Lessons from Ray Gallon on cognitive UA design

Context is everything: Support your users in their integrated competency learning and embed user assistance in the user interface and conceptual context in task topics. That’s in a nutshell what I took away from Ray Gallon‘s  webinar “User Become Learners”, the first in a series of 3 webinars on “Cognitive Design for User Assistance“.

To catch up before the second webinar on Tuesday, 29 January, read on or watch the recording made available by Adobe who hosted and sponsored the webinar (requires an Adobe ID) or check out Ray’s slides.

Evolving learning needs

What we need to learn changes all the time – it even seems to change faster these days. So for us technical communicators, says Ray, it’s not sufficient to show users how to use or learn a product. Beyond that, we need to teach users how to learn to adapt a product to their evolving needs.

To back up his claim that learning needs are not static, Ray showed OECD statistics for the last 50 years: In average European working days, routine manual tasks are down. Routine cognitive tasks way down. Non-routine manual tasks are way, way down. By contrast, expert thinking is way up. And complex communication is way, way up!

To help users meet these challenges, technical communicators need to offer decision support and to convey knowledge. Users need to be able to decide which problem they need to solve and if and how they can go about it. This requires knowledge: They need to understand contexts, underlying concepts and applicable tools. All this means much more than just explaining a product’s user interface – which would be routine manual and cognitive tasks that are on the way out.

How minimalism can help

Ray recalled the core principles of decision support, according to the U.S. National Research Council. Half of them relate directly to the tech comm principles of minimalism (as summarized by JoAnn Hackos on her blog recently):

1. Begin with the users’ needs in decision support; focus on users’ actions in minimalism
2. Connect information between producers and users in decision support; understand the users’ world in minimalism
3. Design for learning in decision support; ensure that documentation is findable and contains troubleshooting information in minimalism

Just because minimalism emphasizes hands-on practice doesn’t mean it shuns conceptual information, says Ray. So to add value to the documentation, describe applicable tasks, not just the user interface.

That means we tech comm’ers don’t just merely describe the menus and icons. Instead, we must also get involved in the design of the product, especially the interface with its labels and error messages and pop-up hints.

This way, usage of our documentation can improve drastically: Rather than supporting rote memorization or, worse yet, require users to look up the documentation repeatedly, users can learn from the documentation and apply what they find to decide what they need to do and how.

To carve up or synthesize?

One of the most important consequences of Ray’s paradigm for us tech comm’ers is that it effectively abolishes a dear dogma of topic-based authoring, namely the separation of concepts and tasks. Ray explains that just because we need to understand these areas separately (when we make sense of products during analysis) doesn’t mean we need to keep them separate when we present them again to users (during synthesis). Imagine a pizza: You need to understand crust, tomato sauce and toppings separately – but you would never serve them separately to the user. (For more about this, see Mark Baker’s blog post.)

For documentation, this means to empower the user: Read/understand once, apply many. I think the parallel to single sourcing is obvious and deliberate: Write once, use/publish many. Give users all the information they need – and only that, no more, nada mas! (And offer it in a way it’s findable immediately.)

Specifically, put conceptual information where it is most useful, into tasks. Integrating conceptual information into tasks avoids that concepts remain abstract and removed. In addition, progressive disclosure can help with the efficient embedding of user assistance into the user interface.

My lessons learned

I think Ray’s approach makes a lot of sense. It can improve many a help system that follows the letter, but not yet the spirit of topic-based authoring.

But two factors in my daily work dampen the effect of Ray’s ideas for me:

• We use a DITA-based information model which allows and in fact encourages contextual information as part of task topics. We want to ensure that users understand when they need to perform a task and why. I believe the <context> and also the <prereq> element in DITA serve this purpose well, without fully replacing concept topics.
• Ray’s assertion that “good user assistance is only needed once” is a bit too idealistic for many software products I have documented. Many are very complex, some are poorly designed to boot to allow the user to safely deduce a general principle about the product. So Ray’s paradigm does require not merely the technical communicator’s participation in the design phase, but actually good design. As Ray said during the Q&A session, “This is easy to explain, but hard to do.”

Advertisement

Top 6 tech comm trends for 2013

Flexibility in several dimensions is my tech comm mega-trend of the year, after mashing up the top 6 trends presented by Sarah O’Keefe and Bill Swallow in Scriptorium’s annual tech comm trends session. Head on over to Scriptorium’s site to watch a recording of the webcast and to read Sarah’s take on the trends she presented.

1. Velocity

Velocity is Sarah’s first trend which simply means that we tech comm’ers are expected to create, deliver and update content faster than before. Also gone are the days – or months – when localized documentation could be several weeks late.

If we are serious about this, we need to revamp our documentation processes. I agree with Sarah: A recent restructuring of documentation processes has sped up my throughput and made my estimations more predictable. So it has improved my productivity as a whole.

It’s also made me more flexible because my smaller task packages take less time before I finish with a deliverable. It used to take me 4 to 6 weeks to update a user manual, so interrupting this task for something more urgent was expensive because it further delayed the manual and also clogged up my pipeline. Now I take about 2 weeks for the same task which allows me greater flexibility in sequencing my tasks because I still have a chance to finish the manual by the end of the month, even if we decide that I first spend a week on something else. I could not have achieved this  flexibility without revamped processes to analyse and specify documentation and without a topic-based approach.

2. PDF is here to stay

Bill’s doesn’t see PDF go away any time soon, if only because it’s durable, controllable, reliable and downward compatible to that other durable format called print-on-paper. Google Docs might be a potential competitor, but Bill doesn’t see it making great advances on PDF in 2013.

As comments from the audience showed, there seems to be a lot of passion about the issue and some people can’t seem to wait to lay the last PDF to rest, finally. As a tech writer in semi-regulated industries, I know that I’ll be creating PDFs for my users for a looong time. It might not be a trend per se, but I agree with Bill that we haven’t seen the end of PDFs just yet.

3. Mobile requirements change technical communication

Mobile will be the big game-changer for tech comm this year, predicts Sarah. Requirements for mobile documentation mean that PDF will be one format of many – and maybe not the primary one in many cases. Other essential deliverable formats include HTML5 (for an online audience) and apps (for native or offline use).

The limited real estate of mobile devices requires more flexibility in how we structure and present documentation. Progressive disclosure can help us to integrate essential user assistance in labels or pop-ups. Beyond that, we need a strategy of what to disclose where and how to create a seamless and consistent user experience.

4. Mobile drives change

Similar to Sarah’s trend, Bill underscored the influence of mobile documentation. He emphasized the need for concise, no-frills content. Rather than jump on the progressive disclosure, Bill presented an alternative scenario: An “executive” device with the main product hooks up with a second, mobile device which presents the corresponding documentation. (I didn’t quite understand this point, I think Bill mentioned a second screen embedded in the primary device, but I’m not sure.)

5. Localization requirements increase

Bill sees the scope of localization expand as the need for translation no longer stops with external documentation. Increasingly, internal documents also need translations because corporations need to keep international teams afloat and cannot afford to lose traction due to vague or misunderstood communication.

This is also the reason why, economic advantages notwithstanding, machine translation hasn’t taken off yet. But a hybrid process seems promising in some areas where machine translations become useful and reliable after human editing. Enter flexibility as our audience now might also include far-flung colleagues – and our tasks might include editing text that’s been translated by robots.

6. Rethink content delivery

As we face diverse requirements for working at different speeds in more formats and for more diverse audiences, we need to be flexible and rethink what we deliver and how. With demands like these, pages of static contents are frequently not sufficient. Instead, users need more dynamic content and filters to customize the documentation to what they need at the moment.

Someone in the audience summed it up very well: “Think of content as a service, not a product.” To me that makes a lot of sense, because it emphasizes the recipient of that service and their situation over the static dead-on-arrival quality that comes with a tome of printed pages.

My summary

I think flexibility is a key ingredient in many of the trends Sarah and Bill discussed with the audience. The recent opportunity to reorganize how I create documentation has given me two kinds of confidence: I have a suitable process in place for now. And I can change processes and methods when I need to.

A secondary trend occurred to me as well: Thanks to Sarah’s spirited mc’ing by which she included the majority of audience questions and comments, this webcast felt a lot more communal than previous ones I have attended. It was almost like single-session, virtual mini-conference. And if industry leaders can bring us together outside of conference season, we can strengthen our networks and move our profession forwards – with just a little bit of flexibility.

Tech comm communities are people, not tools

There’s not a single social media tool or channel that’s the vital “one-size-fits-all” connection for our diverse tech comm community, but it’s their combination that lets us thrive, as I’ve learned last week.

On Thursday, a colleague and I ran into an obscure problem with review packages in our help authoring tool, MadCap Flare. We didn’t find a solution in Flare’s online help, so I reached out to a user forum.

Peer/user forums

MadCap Software Forums are provided by MadCap, but they’re run for and by the community of MadCap users. I first searched existing threads to see if someone had encountered the same problem before, without success. But I did find a thread where two days earlier two users, V. and M., had run into a similar problem that we had also encountered – and solved.

In the communal spirit of give-and-take, I outlined our solution. (The trick hinges on knowing that Flare’s review packages are really zip files which you can unpack and manipulate – if you know what you’re doing.) Then I posted our own query.

Within 24 hours, M. posted three replies:

1. To confirm that our solution indeed works, at least in some circumstances – hence we were on to something useful that was worth sharing.
2. To post MadCap’s reply to her support case which essentially had the same steps as our solution – hence we got our DIY solution sanctioned by MadCap.
3. And to point out that our solution can also help us address our own problem – hence we basically couldn’t see the forest for the trees, and needed a fresh pair of eyes to consider our issue. 🙂

So it turned out that both my posts to the forum paid off. – But a small detail nagged me: M.’s greeting on the forum sounded like we knew each other, but her user name didn’t ring a bell.

Conferences

Flashback to October 2010, when I attended TCUK, the annual conference of the UK tech comm association ISTC. It was only my second tech comm conference, and the first one where I presented. My talk “Getting ahead as a lone writer” summarized my experiences and lessons learned when I had an opportunity – rather than the explicit task – to raise the quality and profile of the documentation. (You can also read about the talk in my earlier posts.)

I was really nervous the night before my talk and was very lucky to find a fellow tech writer and scheduled speaker to confide in. Karen Mardahl lent great moral and practical support. This chance encounter is another succes story: Karen has since become a good friend of mine – and most recently even a colleague!

My talk went well, and from comments I could tell that some tech comm’ers in the audience got something out of it, whether it was an ideas to try and implement or a more general sense that it might be possible and worthwhile to get ahead as a lone writer.

The feedback has been very helpful by reminding me that even minor points are helpful to some. And conversely, my biggest lesson may fall flat if no one has that same problem – or I don’t present it in a recognizable way… 🙂 Since then, I try to let conference speakers know when something struck a chord, whether it’s some practical advice or an alternative perspective on things.

Mailing lists and groups

As a member of ISTC, I get a daily digest of the association’s mailing list. I must admit I haven’t gotten a lot of use out of it so far. Maybe it’s because much content is specific to the UK, such as meetings of area groups. But Friday’s digest had an entry that merits its mention here: M. had posted, using the same user name as on the Flare forum and her full name.

Now I knew who it was: One of the attendees of my talk at TCUK 2010! We had been connected on LinkedIn for a while, so I sent her a message to thank her for her advice.

It’s the people, not the tools

I sometimes think that the tech comm blogging scene may be slowing down. At other times, I wonder if I really need yet another mailing list. But as last week’s experience has taught me, different channels have different uses to connect me to other tech comm’ers. So ultimately, it’s not about this channel or that app – it’s about connecting with people. And I, for one, am glad, proud and humbled to be part of such a vital professional scene which is stronger than any one channel.

Recommended free tech comm webinars

If improving your tech comm skills was on your list of New Year’s resolutions, then chickening out just got a whole lot harder: There are (at least) 4 first-class webinars in the next 4 weeks, so you can attend them anywhere you have Internet – and they’re free, too!

Tech comm trends for 2013

Sarah O’Keefe‘s Scriptorium rings in her webinars this year with another instalment of annual trends, intermittently delivered as blog posts. I recommend this webinar on the strength of Scriptorium’s previous predictions: Even if they didn’t affect my job directly, I’ve found their trends thought-provoking and relevant.

To see how right they’ve been, check out my coverage of their trends for 2012, 2011 and 2010. My guess for this year is we’ll hear about documentation for mobile devices and more about the intersection of tech comm and content strategy.

The 2013 edition on Thursday, 17 January at 11 am EST / 5 pm CET will be special in two regards:

• Scriptorium solicited nominations for trends on twitter last month.
• The webinar will feature Bill Swallow as guest.

Given Sarah’s knack to sniff out industry trends and Bill’s penchant for lively discussion, this should be an excellent webinar.

Cognitive Design for User Assistance

Ray Gallon and I share a passion for exploring what makes tech comm tick: I’ve explored some of its cognitive foundations in my presentations “Pattern recognition for technical communicators” and “Addicted to meaning“. Now Adobe sponsors a series of 3 webinars where Ray talks about “Cognitive Design for User Assistance“:

1. Users Become Learners
2. Empowering User/Learners Through Cognitive Development
3. Integrated Learning: Building Customer Loyalty

I’ve heard Ray give a condensed whirlwind tour of the same area in his presentation “The Hairball of Content” at TCUK12. I’ve found it very stimulating: Ray has a unique way to tie high-level concepts, such as cognitive development theory, to applicable guidelines and examples. I’m looking forward to seeing how tech comm can “help users learn principles that they can transfer from one use case to another” and how to get that to work using topic-based authoring and DITA structures.

The webinars are at 1pm EST / 7 pm CET on Tuesday, 15 January, Tuesday, 29 January, and Monday, 4 February.

Disclaimer

Neither Sarah nor Ray have promised me anything to plug their webinars – in fact, they don’t even know I’m doing it, but I trust they don’t mind… 🙂