STC13: User Assistance, Tech Comm, and Learning

The session “User Assistance, Tech Comm, and Learning” brought together four seasoned professionals to discuss common grounds between tech comm and e-learning: Nicky Bleiel, who moderated, Kevin Siegel, Saul Carliner, and Matt Sullivan. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

The panel, moderated by Nicky Bleiel. Photo by @viqui_dill.

Saul’s opening statement pointed out important differences between tech comm and training:

• Tech comm doesn’t aim at information retention, but training does.
• Tech comm’ers mainly create content, but trainers mainly teach, whether online or “in real life”.

Yet there are large overlaps between the disciplines and their practice, especially in “informal learning”, specifically, in the purpose, the content, and the consumer’s awareness of learning.

Kevin added further common values and features which both share:

• Brevity in topics, in e-learning lessons (typically less than 5 minutes), or in a video (less than 2 minutes)
• Step-by-step instructions in task topics and lessons
• Direct address of the user as “you”

Matt explained how he focused on pragmatic information delivery where his single-sourcing workflow almost automatically combines “teaching and telling” in documents.

In the discussion that followed, the panelists addressed further aspects of that intersection of tech comm and training:

• By emphasizing user action and tasks over functionality descriptions, you can offer resourceful users interactions and showing and telling to mix and match. However, exactly targeting your audience always precisely is usually not possible (neither in training nor in tech comm), so resist the temptation to “helicopter-parent” your learners.
• That intersection works well with thought-through minimalism (which is not the same as writing in a concise manner).
• Selecting the right channel and format can benefit both purposes, tech comm and training, tremendously, whether you choose videos or interactions or text.
• Sample projects can be helpful to support and illustrate both,  learning and, to a lesser extent, documentation. They can be used as templates for a quick start to explore user scenarios. Personas are a great idea, too, but they’re of limited value as long as they don’t support the person(a)’s task.

In closing, the panelists pointed out that the focus of tech comm and e-learning alike is on people, not theories, methods or tools. In either domain, all users are different and many are extrinsically motivated by policy, law or certification to learn. So make it easy on them and keep them moving along swiftly.

Advertisement

Getting mileage from a tech comm mission statement

If you have a mission statement for technical communications, you can use it to anchor several strategic and tactical decisions. I’ve suggested a few general reasons Why you need a tech comm mission statement in my previous post. The valuable discussion that ensued led me to think we can get some mileage from a mission statement in some high-level tasks further downstream.

Consider a mission statement that says: “Our product help provides users with relevant product information at the right time in the right format.”

Defining audiences and deliverables

You can keep your audience in focus with a mission statement. Do you write for end users? Maybe there are different types, such as professionals vs. amateur hobbyists? Do you also address colleagues who expect to find internal information in the documentation? The mission statement above doesn’t specify it – and hence can be expected to address everyone who uses the product.

You can also derive your deliverables from a mission statement. Do you publish to several formats or only to one? What is your priority of formats? Web help first, PDF second seems a standing favorite that’s recently been disrupted by the emergence of mobile output. The mission statement above merely mentions the right format – so you need to figure out what format is right for your audience types. You can use personas to determine how your users work with the product – or better yet: Observe or survey them!

Defining information model and processes

You can derive your information model, the structural standard of your documentation, from your mission statement. This model should help you to reach the goal described in your mission and serve your audience. For example, topic-based architectures have long been popular. If you need to retrieve small chunks of information, for example to share steps in a task or exception handling advice, consider a more granular standard such as DITA.

Your processes should outline a repeatable, efficient and effective way to create your deliverables so they address your audience and, once again, help you to achieve your mission goal.

Your information model can suggest which topics or elements to create need to be created and updated for a given product or enhancement. Together with your processes, this makes it easier to plan and estimate documentation efforts – in theory at least…

– But with some management support and some persistence, a mission statement and some strategic decisions piggy-backed on to it can help you get out of the proverbial hamster wheel.

What do you think? Can this be helpful? Or is it too far removed from real life? Do you have any experience with a larger documentation strategy based on a mission statement? If so, did it work?

Scott Abel on Structured Content at TCUK12

Scott Abel delivered his keynote It’s All About Structure! Why Structured Content Is Increasingly Becoming A Necessity, Not An Option in his usual style: Provocative, but relevant, fun and fast-paced (though he said he was going to take it slow). He even channeled George Carlin’s routine on Stuff: “These are ‘MY Documents’, those are YOUR documents. Though I can see you were trying get to MY Documents…”

His style doesn’t translate well onto a web page, so I’ll restrict myself to his 9 reasons Why Structured Content Is Increasingly Becoming A Necessity:

1. Structure formalizes content, so it can guide authors who need to make fewer decisions when writing it. It also guides readers who can find more easily where the relevant information is in the whole documentation structure or within a topic. And it guides computers which can extract relevant information automatically and reliably.
2. Structure enhances usability by creating patterns that are easy to recognize and easy to navigate with confidence.
3. Structure enables automatic delivery and syndication of content, for example, via twitter – and you’ll be surprised occasionally when and how other people syndicate your “stuff”.
4. Structure supports single-sourcing which means you can efficiently publish content on several channels, whether it’s print or different online outputs, such as a web browser, an iPad or a smartphone.
5. Structure can automate transactions, such as money transfers, whether they are embedded in other content or content items in their own right.
6. Structure makes it easier to adapt content for localization and translation, because you can chunk content to re-use existing translations or to select parts that need not only be translated but localized to suit a local market.
7. Structure allows you to select and present content dynamically. You can decide which content to offer on the fly and automatically, depending on user context, such as time and location.
8. Structure allows you to move beyond persona-ized content. This is not a typo: Scott doesn’t really like personas. He thinks they are a poor approximation of someone who is not you which is no longer necessary. With structured content (and enough information about your users) you can personalize your content to suit them better than personas ever let you.
9. Structure makes it much easier to filter and reuse content to suit particular variants, situations and users.

But do we create documentation with meaning?

Being meaningful is an essential, but elusive feature of good technical communications. Yet being meaningful in technical communications is just as essential as being correct and clear, concise or consistent: Understanding how and why communication is meaningful can help you to make your documentation more effective and to make your product more useful.

What is meaning?

Information theory suggests a hierarchy of information which proceeds from data at the bottom via information and knowledge to wisdom at the top. For example:

• Data is the sheer fact that the Microsoft Office 2007 software has an “Office button” icon in the upper left corner.
• The information is that this icon gives you access to functions such as opening, saving and printing a file helps you with generic functions.
• The knowledge is that this functionality has replaced the File menu you’ve been used to. This adds meaning and supports your active experience.
• The wisdom might be in the affirmation that nothing lasts. Or that Microsoft has flipped-flopped when they abolished something as sensible as the File menu – only to bring it back in Office 2010…

So meaning occurs at the knowledge stage in this hierarchy when you make sense of data and information, when you “connect the dots” into something that you can apply purposefully. Meaning gives answers to questions such as “So what?”, “What does this mean for me, in my situation?” and “Why should I care?”.

Why should technical communicators care?

Technical communicators should care about meaning, because we are in the business of creating meaning and transmitting it to users. We can provide all the data and information we want, if it’s not meaningful to customers, it’s wasted and dead. Any time documentation fails, it’s either because meaning has not been created or not been transmitted successfully. Documentation that merely informs the user “To print a file, click the Print button” does not support any active experience. It does not create any meaning, if it omits the context, such as the task the user may be engaged in, the prerequisites and the expected results of the user’s action.

– How can we ensure that our documentation is meaningful? Should we be thinking about meaning explicitly? Or is it enough to know our audience, use personas and create task-oriented documentation? Feel free to leave a comment.

A. Ames & A. Riley on info experience models at STC12

Andrea Ames and Alyson Riley, both from IBM, presented a dense whirlwind tour on “Modelling Information Experiences” that combine four related models into a heavy-duty, corporate information architecture (IA).

While the proceedings don’t include a paper on this session, Andrea posted the slides, and the presenters published a related article (login required) “Helping Us Think: The Role of Abstract, Conceptual Models in Strategic Information Architecture” in the January 2012 issue of the STC’s intercom journal.

The session proceeded in six parts. First, Alison explained IA models in general and how they work. Then Andrea described each of the four model types that make up an IA specifically.

IA models as science and art

Information architecture relates to science as its models draw on insights and theories of cognition. And its models relate to art as they aim to create a meaningful experience. Both aspects are important. Only if IA models manage to blend science and art can they touch the head and the heart.

The session focuses on IA models instead of theories (which are too vague and abstract) or implementations (which are too specific and limited). Thanks to the in-between position of IA models, we can use them to

• Ask the right questions to arrive at a suitable, feasible IA
• Tolerate the ambiguities of “real life”

Models present descriptive patterns, not prescriptive rules. They don’t say how stuff must be, but how it can be represented. They differ from real life, but real life is still recognizable in them.

That means you cannot simply implement a model on autopilot and get it right. Instead, you have to

• Think how to implement the model
• Vary the model for your users’ benefit
• Listen to the right knowledgeable people when implementing

Models help you think

To arrive at your concrete IA, you take the model’s abstract patterns and apply your project-specific details to them, the who, what, where and when.

This task is less mechanical and less copy-and-paste than it sounds. It’s not so much a question of following rules and recipes, but of making abstract patterns come to life in a coherent, flexible whole. (If you’ve ever tried to create meaningful concept or task topics by following an information model, you know it’s more than just filling in a DITA template. You need to use your own judgment about what goes where to achieve and maximize user benefit.)

Since there are four related models, you need to think carefully how each of these models should benefit your users. And the models help you think, they scale and adapt to:

• How your business and its information requirements develop over time, how they grow and expand in desired directions
• How your customers find, understand and apply the information they need

The four IA model types

The IA model that Andrea then explained consists of four related model types:

use model (content model + access model = information model)

Each of these model types needs to be developed and validated separately.

The use model defines how users interact with information. It describes standard scenarios for optimal user experience within the product or system context. It outlines what information users need and why and how they use it. It includes use scenarios for the entire product life cycle and user personas that outline different types of users. Fortunately for us technical communicators, Andrea pointed out, describing all this is part of our core skill set.

The content model defines how information is structured effectively. This could be DITA (in the case of the company I work for, this is what we call our DITA-derived “information model”). It includes the granular information units and their internal structure, for example, task topics and their standard sequence of contained information. It also describes how these granular units are combined into deliverables.

The access model defines how users access the information efficiently. It makes provided information useable, thanks to a navigation tree, a search function, a filtering function to increase the relevance of search results, an index, etc. Artefacts of this model type are wireframes, storyboards, a navigation tree and the like.

The information model defines how users get from one stage to the next. It uses the other three model types as input and fills in the gaps. It combines the content and access models which probably work fine during the installation and configuration processes, but may not yet carry a user persona from one stage to the next. As such, the information model is sort of the auxiliary topic that you sometimes need to insert between concept, task and reference topics to make a complete book out of them. At the same time, this model type is more detailed than the use model and closer to the other two types.

My takeaways

I was extremely grateful for this session and rank it among the top 3 I’ve seen at the summit – or any tech comm conference I’ve been to! Yes, it was fairly abstract and ran too long – my only complaint is that it left only 2 minutes for discussion at the end.

As abstract as much of the session was, it actually solved a couple of problems I couldn’t quite put into words. After designing and teaching our company’s DITA-derived information model (which is a “content model” by this session’s names), I thought our model was applicable and useful, but it had two problems:

• Our model lacked context. – Now I know that’s because we haven’t mapped out our use model in the same detail and failed to connect the two.
• Our model was baked into a template for less experienced writers to fill in – with varying results. – Now I know that’s because the models are not supposed to provide templates, but require writers to use their own judgment and keep in mind the big picture to deliver effective information.

Another lesson I learned is that many structured information paradigms seem to include a less rigid element that sweeps up much of the miscellaneous remnants. In DITA, there’s the general topic which is used for “under-defined” auxiliary topics to give structure, especially to print deliverables such as manuals. In this IA model, there’s the information model which fills the gaps and ensures a more seamless user experience than the other three models can ensure.

– For an alternative take, see Sarah Maddox’ post about this session.

How (not) to use documentation checklists

Checklists can be great aids, but they won’t guarantee that you create good and complete documentation. – That’s my experience, and I’d appreciate your input whether you agree or not.

The Valuable Content Checklist

Content strategist Ahava Leibtag published the “essential Creating Valuable Content Checklist (TM)” last month, along with a step-by-step guide:

With this checklist, you can ensure that your web content is

• Findable – because it has a headline, title, keywords, links, etc.
• Readable – because uses chunking, bulleted and numberes lists, etc.
• Understandable – because addresses user personas and their proficiencies, context, etc.
• Actionable – because it gives readers incentive to act, comment, share, etc.
• Shareable – because it gives readers a reason and the means to share, etc.

I think Leibtag’s checklist covers a lot of essential features of good documentation, so it should also work well for technical communications. (The book Developing Quality Technical Information by Gretchen Hargis, et al., also contains great checklists for documentation.) But then I had second thoughts…

Clear and simple

The good thing about checklists is that the best ones are clear and easy to use. They remind you of things you may forget otherwise. One of the most impressive recent examples of their benefits has been in medicine: Peter Pronovost’s checklists have shown to improve the delivery of critical care. (Atul Gawande reports on them in the New Yorker of 10 Dec 2007.)

Seductively simplifying

The bad thing about checklists is that they are so clear and simple, it can be seductive to rely on them for things they cannot do. You can check off all items on your checklist, but you may still create

• Incomplete documentation, when you’ve missed a sub-topic, keywords, links, a persona or a use case.
• Useless or bad documentation, when you describe an unintended or even dangerous way of using the product.

In other words: You get what you measure. If checklists are your tool, you will get formally complete documentation, which may or may not be helpful to customers.

As simple as possible, but no simpler

I think the solution lies in the quote attributed to Albert Einstein: “Everything should be made as simple as possible, but no simpler.” That’s good advice for documentation in general, and for checklists in particular. This means to me:

• Use checklists only after writing a topic to verify that it satisfies formal completeness standards.
• Avoid checklists while writing a topic when I focus on content and quality, specifically on usefulness and applicability for users or personas.

I also appreciate that structured writing already separates layout and content, so I can use my “freed-up brain cycles” to focus on content and not go on auto-pilot and simply fill in topics with bits and pieces while ticking off check boxes.

Your turn

Do you think checklists do more good or harm in technical communications? How do you use them to make sure they improve your documentation, but don’t compromise it? Please leave a comment.

Shape the hype cycle with tech comm

You can use technical communication to accompany and even nudge technologies and products along the hype cycle.

The hype cycle

The hype cycle was invented by Gartner Research in 1995 and has since been underlying dozens of their reports. Here’s a schematic example:

image from http://newsletter.stc-carolina.org/

You can see how it tracks visibility and expectations of a technology across time in 5 stages, from the Technology Trigger up to the Peak of Inflated Expectations and down into the Trough of Disillusionment, then slowly up the Slope of Enlightenment, until it reaches the final Plateau of Productivity.

I think there a few remarkable things about the hype cycle:

• Let’s get the obvious out of the way: It’s not a cycle at all, but a curve… 🙂
• Different types of companies may engage in the cycle in different stages. That means the hype cycle is not some fate to be endured, but something that can shape corporate strategy – and by extension content strategy.
• The hype cycle is not just for managers and marketeers. It speaks to our industries as well: Tech comm consultant Sarah O’Keefe started an article on “The Hidden Cost of DITA” with it in 2008 (that’s where I got the example above). And UX designer Ron George put one up on his blog last year.

Enter technical communication

So what does technical communications have to do with it?

We technical communicators provide the words around stuff on the curve. So we can put a spin on them, to a certain extent. I don’t think we can move a technology or a product into a totally different stage with documentation. But I believe we can mitigate adverse effects and nudge our subject along the curve a little.

There are two reasons why this works:

• Technical communication is part of the hype cycle. Whether we take it into account or not, our documentation contributes to the item’s visibility, and it certainly shapes expectations on it.
• Technical communication can be dynamic and agile. It is usually quite easy and fast to change the technical communication in contents, tone and spin to address a new use case, an additional persona or a different audience.

And there are several ways how you can use technical communication to influence the hype cycle:

• It’s all about context. You know this already, if you’ve ever thought about personas, your audience and their situation when they are using your product. So take into account the hype cycle, especially that difficult phase into and out of the Trough of Disillusionment. “First contact” documentation such as quick starts are particularly suited to address inflated expectations and to offer a shortcut to the Plateau of Productivity.
• Position yourself as the users’ advocate who accompanies them along the curve. Who is better suited to guide them up the Slope of Enlightenment than us technical communicators? Keep visibility of the product and its benefits up (to the limited extent that you can), and keep users’ expectations realistic.
• Engage with the users. Hiking up a slope in silence is no fun. Find out what interests your users, what they try to do and where they want to go with the product, whether by soliciting feedback or user-generated contents. (But don’t forget to check back with your diligent product manager about the general direction…)

Your turn

What do you think? Should you, can you write with the hype cycle in mind? How can it affect the relationship between technical communications and marketing?

Top 10 things that users want to do in a help system

Truly helpful help systems are more than a set of instructions and information. They offer a constructive, pleasant user experience that make users happy and efficient. Which makes help systems comparable to libraries or department stores…

David Weinberger has an interesting analogy how information systems in general are like – and unlike – retail stores in the beginning of his book Everything is Miscellaneous. You can read the prologue and chapter 1 online.

Here are 10 things that users want to do in a help system – or a library or a department store… Some of them are kind of obvious, but I think it helps to consider all of them and how they relate to functions and options in a help system. Which ones you want to offer depends on your users, your product and your tech writing resources.

1. Search

I know exactly what I’m looking for.

Offer useful search results. Duh…

2. Find (and find again)

I know it should be here somewhere. I swear I’ve seen it last time!

Offer filter options to narrow down search results by topic type, task type, persona, etc., so users don’t have to guess how your topics are structured or how to rephrase their search. Allow users to save search result lists and to bookmark favorite topics.

A good discussion how users search and find in different ways is in Morville’s and Rosenfeld’s book Information Architecture for the World Wide Web, chapter 3 “User Needs and Behaviors”.

3. Know their way

I know where it is… – Now how did I get here? How do I get back?

Offer navigation aids such as a table of contents, browsing sequences and breadcrumb trails, so users can

• Explore topics in context,
• Look up their current location in the system,
• Backtrack their steps.

4. Browse (as in “shopping”)

I’ll know what I want when I see it.

Offer tags that describe and group topics, so users can quickly get to the right section and dive in.

5. Get advice

I don’t know what I need. This is all new to me.

Recommend tutorials, best practices, what’s new, tips & tricks to guide novice users – and visitors who wonder about the learning curve of your product.

6. Recognize items

What is this thing? What does it do? The box doesn’t say.

Offer clear and, if possible, unique topic headings so users are confident they’re looking at the appropriate item.

7. Compare

This isn’t quite what I’m looking for… Do you have something similar?

Offer a selection of related topics.

8. Ask a human

What does this mean? I don’t understand this. This doesn’t seem to work!?

Offer options to send an e-mail, or a request for service, callback or chat to your company.

9. Share

This is cool! Here’s my comment. My friend/colleague should see this!

Offer ways for users to submit feedback, comments, ratings. Allow users to e-mail or tweet a topic.

10. Take stuff home

I’ll take this!

Allow users to print or make a PDF of one or several topics.

Your turn

Which use cases do you find essential? Have I missed any? Or could you do without most of them as long as your search rocks?