Ray Gallon’s Hairball of Content at TCUK12

Ray Gallon‘s session The Hairball of Content was a high-level tour de force where he argued that we technical communicators do much more than just technical writing. However, we rarely get credit for all the other work we do in tasks such as content strategy, user interface design, information architecture, etc.

Assisting the user

Our overarching task is to assist users by translating the functional thinking of engineers into something that users can act upon and experience. That means our content is not just in the documentation, but it’s also in the user interface, in the error messages, etc. So technical communications accompanies the complete design process – and we tech comm’ers need to be involved from day one.

If we take our role as the users’ advocate seriously, we need to tweak some of our dogmas a little to ensure that users get the maximum benefit.

Embedding fosters knowledge

Concepts as documentation content are not an end in itself, but they need to offer decision support to users. A concept should tell readers whether they are looking at the right tool or function at the right time. That means such conceptual information needs to be available right where it matters. Even if it means to give context with conceptual information inside a procedure topic, either in the introduction or even as a short sentence in the individual step.

Yes, such mixing of topic information goes against the rules of topic-based authoring, but it will actually help users: Offering such mixed information in context transforms the sheer information of how to do a task  (which is hard to remember) to knowledge of why and how to do a task (which is easier to remember.)

Context is everything

Ray said: “Context is everything” – which applies across the board:

  • User assistance needs to be available in the context of the user’s workflow. Embedding contextual information in layers, from GUI labels via tooltips to full-blown help topics, will support users accomplish their tasks faster and more easily without taking more of their attention than necessary.
  • Each piece of user assistance also needs to offer sufficient context to be meaningful and “learnable” for users: Only offering steps 1 through 5 in a procedure usually doesn’t offer enough context for users to actually learn how to use a product or a function, if we omit the “when” and the “why”.
  • User assistance also needs to offer enough context to allow users to navigate easily and with confidence through the product and the documentation. Specifically, we need to offer users an easy way back to where they’ve come from and a way back to the product and their task.

Offering successful user assistance isn’t a question of offering more at all costs, because more information isn’t necessarily better for the users. Instead, we need to stimulate cognitive demand, the will to know and learn, in the user by offering the right information at the right time.

TCUK12, day 1: Workshops & company

The first day of the ISTC conference TCUK12 offered workshops and great opportunities to meet tech comm’ers from all walks of life and many corners of the earth.

When I arrived late on Monday evening, I promptly headed for the bar and joined the advance party for a last round – which lasted so late that I’m not even sure in which timezone it was 2 am before I turned in…

Robert Hempsall: Information Design 101

Robert Hempsall offered a great and engaging hands-on Information Design 101 workshop about information design. The workshop focused on the five key areas of content and structure, language, layout, typography, and lines and spatial organization. Using a formal application to vote in English elections by mail, Robert led us through the process of designing the form to maximize clarity and usability.

Thanks to our versatile and engaged group of delegates, our work on the form was not only lively, but showed how different disciplines contribute to the solution of better information design, from tech comm (with its principles of minimalism and parallelism) via user interface design (with its emphasis on making completion of the form as easy and painless as possible) to graphic design.

In this sense, the workshop presented a good example of “design by committee” (which is usually a terrible idea): We discussed the most intuitive and user-friendly sequence of the form’s elements and how best to phrase the section headings, as questions or as imperatives. A seemingly innocuous “all of the above”  check box also caused a debate: Should it precede the individual options, to make completing the form quick, easy and painless? Should it come last, so users hopefully first read and reflect on the options? Or should it be omitted altogether, so users have to think about each option and select all that apply.

Form design is maybe not among the core tasks for many tech writers. Yet I’ve found several challenges in it that are strikingly similar to getting a topic structure just right, whether it’s a consistent, indicative heading, good, clear instructions or logical structure.

Rowan Shaw: Quality Across Borders

Rowan Shaw‘s workshop Quality Across Borders: Practical Measures to Ensure Best-Value Documentation in Global Technology Businesses focused on creating documentation both with authors and for users who have English as a second language (ESL).

As in introduction, Rowan presented us with 10 sentences each of which had some element that can create a problem for ESL readers, ranging from “10/03/12”, which could mean 3 October or March 10, to metaphors and slang.

If you need to hire ESL authors, it can be helpful to ask applicants to sit for an exam which tests skills such as procedure writing, fluency of expression, structuring, detail, consistency – but also their motivation for applying, to spot those candidates who want a foot in the door, but might not be interested in tech comm in the long term. We discussed a sample test, whether it was applicable and appropriate in all cultures.

Rowan suggested that, given the practicalities of global ESL authors, you might have to settle for less than perfect profiles in candidates. Then it is important to know which skills are easier to teach someone on the job, for example, grammar, structuring, capitalization, punctuation and how to use a style guide. Other skills are harder to teach, such as an eye for detail, audience orientation, logical thinking, but also more intricate language skills, such as prepositions and correct modifiers.

Again, this workshop benefitted tremendously from the diverse talents in the room and the experiences delegates brought to the topic.

The right company

I keep harping on how much I enjoy and benefit from meeting other tech comm’ers. Just on the first day:

  • I found that several other doc managers are also wary to hire subject matter experts, who are less committed to tech comm, because they might just want a foot in the door (see above).
  • I had an immensely helpful conversation with someone who’s a visiting professor and who could give me tips and ideas that I can try as I consider teaching as a future path.

So day 1 was very fruitful already, and I’m looking forward to more sessions and conversations to come.

3 motivators you share with your tech comm readers

What motivates you to work most likely motivates most of your users in their jobs, too! You still need to know your audience, their tasks and background, but the good news is that you have some basic motivators in common. And these can help you understand what makes you happy at work – and what makes your users successful in their work with your documentation.

The three motivators

I take my cue from Walter Chen’s post “The science behind what motivates us to get up for work every day“. I want to focus on three motivators Chen quotes from Daniel Pink:

The 3 real reasons that motivate us to work hard every day

Pink explains … that there are in fact just 3 very simple things that drive nearly each and everyone of us to work hard:

  1. Autonomy: Our desire to direct our own lives. In short: “You probably want to do something interesting, let me get out of your way!”
  2. Mastery: Our urge to get better at stuff.
  3. Purpose: The feeling and intention that we can make a difference in the world.

The motivators for technical communicators

Pink’s model resonated with me, and I think this is exactly what motivates me to do good tech comm work and try to get better at it:

  • Autonomy for me means to find something good in the benign neglect that often meets my efforts. Of course, I have specific products, deliverables and deadlines to comply with, but our documentation team is lucky enough to be able to define its own standards and processes as long as they’re feasible.
  • Mastery is the challenge to write better documentation. When I revisit obsolete documentation that I’ve written some years ago, it makes me smile: Seeing where I’m coming from and what I wouldn’t do anymore gives me a sense of progress. I’m still using task orientation and topic-based authoring – but I wouldn’t awkwardly mix concept and task in the same topic like this anymore.
  • Purpose for me is my reward that my readers can be more successful or simply faster in their work if and because I’ve given them the right information at the right time.

So in a very personal, non-scientific way, I could validate these three motivators.

The motivators for documentation users

I don’t think I’m all that different from my readers in this regard. I believe they get motivated by the same things – they’re just in a different job.

So I try to keep in mind the motivators when I structure and write my documentation:

  • Autonomy is tricky, of course. Someone looking up documentation has just given up the autonomy of a self-directed life and needs instruction or information. But I still try to acknowledge this and follow Pink’s advice above: “You (dear user) probably want to do something interesting (or important), let me (give you what you seek and) get out of your way!”
  • Mastery is where tech comm can really excel. By presenting essential information concisely and clearly we can make it easy for our users to master their tasks and their use of our product. For this mastery, it doesn’t matter whether users learn from the documentation and internalize a skill or whether they simply know where they can look up again quickly what they don’t need to remember.
  • Purpose is frequently neglected, I think. Often documentation focuses on the how, and forgets the why. But there is no sense of purpose without a why. Granted, not every topic can address the big questions of life and the universe. But as long as there is an elegant and possibly noble reason for why our product and its tasks are this particular way, it’s worth sharing it. It will give our customers an extra motivation – and make them more loyal users.

Is this what motivates you? Does it work for your readers or do they have other motivations? Please leave a comment.

How meaning works in technical communication

Considering how meaning works in communication in general, it should be easy in technical communication in particular, because several parameters are fixed.

Last week, I asked whether we actually create meaning in our documentation. Today, I take a closer look at semiotics to find out how meaning is created in communication – and specifically in techcomm.

How meaning gets transmitted in communication

Semiotics is a theory that explains communication as the production of meaning between people who exchange messages in cultural contexts. Semiotics aims to explain how communication is meaningful for a reader. (For much more on semiotics, check out Daniel Chandler’s good introduction Semiotics for Beginners.)

Note that the reader is not just a passive recipient of the message, but the active participant who constructs the meaning of a message. That is not to say that the meaning is whatever the reader wants. Rather, the meaning arises from how readers interpret the signs according to shared common conventions. For example, a user will – more or less – assume that a user manual contains photos or schematic images that represent the layout of the product, not an ideological statement, and try to create meaning accordingly.

Semiotics can get quite complex, due to all the moving parts:

  • Signs, such as words or even images, can lend themselves to creating different meanings at different times or for different groups of readers. (Think of ideologically, religiously or politically charged words or images.)
  • Semiotic “codes” can make you feel a member of the group, like your own regional dialect, or they can exclude you, like academic jargon. Whether you feel included or excluded influences your understanding of the message and the meaning you take from it.

However, technical communication suffers less from these shifts and ambiguities, because a lot of our signs and codes are restricted and well-defined. Or are they?

Why meaning seems easier in tech comm

Much technical communication can avoid some of the semiotic pitfalls because it addresses a limited, rather homogenous audience. We can assume a general willingness to learn the applied “code” of descriptions and instructions such as a user manual contains it. A manual can presuppose a certain vocabulary or define it in its glossary. The context is confined to the intended tasks of the products, and the expected outcomes of the tasks should be clear.

With all these major restrictions on communications in place, the user’s path is confined to a tunnel, and all that is left for the manual to do is to put in some lights and a railing to safely guide the readers through.

– If it was that easy, we wouldn’t find meaning in technical communications so elusive – and we wouldn’t despair to get users to follow the documentation. So our daily experience tells us that it doesn’t quite work that way.

– I’ll explore this problem at my presentation “Addicted to Meaning: How Good Technical Communication is Like Bad Magic Tricks” at tekom/tcworld in Wiesbaden on Tue 23 Oct at 1:45 pm. In the meantime, feel free to leave comments or questions below.

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.

TCUK12: Internationalisation as an accessibility issue

Addressing internationalisation and accessibility issues are two complementary ways to make technical communications (as well as products and web sites) more inclusive. Attend a panel discussion at TCUK in October to find out what pitfalls internationalisation and globalisationcan bring and what others have done to address them.

The panelists

The panel brings together four internationally experienced technical communicators:

  • Karen Mardahl is TCUK’s keynote speaker of this year’s accessibility stream. She believes in encouraging technical communicators to develop their skills and knowledge to strengthen their role in any organisation, but especially to do their part in making products and services more inclusive for all people. Living and working in Denmark, she has experienced the subtle challenges of negotiating technical communications in an international, intercultural context first-hand.
  • Robert Hempsall is a specialist information designer whose international clients, such as international airlines and telecommunicartions companies, require forms, bills and letters designed for efficient localisation and maximum accessibility.
  • Ray Gallon is currently an independent consultant, specializing in the convergence of user guidance and usability for international companies such as General Electric Medical Systems, Alcatel, and Ilog-IBM. Ray is currently a member of the international board of directors of the Society for Technical Communications (STC) and past president of the STC France chapter. He shares his life between the Languedoc region of France and the city of Barcelona, Spain.
  • I will be moderating the panel and insert the occasional anecdote or lesson learned from my experience of 13 years of writing software documentation in English that is accessible and useful for users all across Europe.

The topics

The focus of the panel will be a dimension which frequently shuts out wide ranges of customers and users: National borders and the languages and cultural conventions they denote. Internationalization is an accessibility issue in user interfaces and documentation. In several ways, it affects whether you can reach your customers and how well.

For example, in documentation (and user experience design as a whole), language can be:

  • Inclusive when it is comprehensible to customers who speak English as a Second Language
  • Exclusive when it relies on specific cultural conventions, idioms or references, including common items, such as date and time Readability can be

The presentation of examples and entry forms can be:

  • Inclusive when they support different international conventions
  • Exclusive when they are limited, for example, to 5-digit zip codes

How to distinguish corresponding strategies?

  • Localization: The adaptation of product and documentation to a specific market, a locale.
  • Internationalization: The presentation of product and documentation that enables efficient localization in different cultures and languages.

Our panel discussion discusses these issues and more with examples and suggestions how to make technical communications more inclusive in terms of language and culture and hence more successful internationally.

If you know additional questions or topics of internationalisation as an accessibility issue, please leave a comment.

Improve tech comm by knowing a foreign language

Knowing a second language can help your tech comm work in a couple of ways. The benefit is probably not great enough in itself to justify learning a language, but if you have or had other reasons, it’s worth to consider these side benefits.

Making decisions in a foreign language

I got to think about this when I read a story in Wired that “thinking in a second language reduced deep-seated, misleading biases”. Psychologists at the University of Chicago conducted a study (abstract, full text in PDF) that asked “Would you make the same decisions in a foreign language as you would in your native tongue?”

In a foreign language, we use the same experiences and processes to evaluate situations and estimate risks. However, “a foreign language is like a distancing mechanism. It’s almost like you’re a slightly different person,” says Boaz Keysar who led the study (Business Week). According to the study, thinking in a non-native language emphasizes the systematic, analytical reasoning process. Thinking in our native tongue, on the other hand, leaves more room for the complementary intuitive, emotional decision process: “The researchers believe a second language provides a useful cognitive distance from automatic processes, promoting analytical thought and reducing unthinking, emotional reaction” (Wired). (Whether an analytical process yields “better” decisions is an entirely different story…)

Making tech comm better with a foreign language

For the past 12 years that I’ve worked full-time as a tech writer, I’ve written almost exclusively in my second language English, though I did occasionally translate my English writing into my native German. The study’s conclusion that a second language provides a “useful cognitive distance … promoting analytical thought” explains what I’ve experienced in my work in either language, beyond the limits of actual study:

1. A second chance to learn how language works. Many writers I’ve talked to have a solid grasp of their native tongue, but cannot necessarily explain the rules why something is right or wrong. When you learn a second language consciously, you also learn about grammar (again), its powers and limitations. And you can understand how something what works in one language can be similar or even different in another. For me, writing in English certainly made me a more conscientious “grammarian” in either language.

2. Mirroring the “distance” of users. In my experience, the distance that a second language brings is basically pragmatic incompetence: In a foreign language, I’m not as fully aware of the social context, of how time, space and inferred intent contribute to any communication act. I may trip over an idiom I don’t understand, or I may fail to see the irony of a statement and take it at face value.

In tech comm, this linguistic challenge is actually a benefit, because many of my readers share in that distancing experience. My readers may read my documentation in their second language. Or they might use the product in a context and for a purpose that is more or less different than intended and documented. This is why localization is harder than just translation. Internationalization can even become an accessibility issue, when a product no longer works properly in a certain context. So facing similar pragmatic uncertainties makes me a better advocate of the users I write for.

Your turn

If you know a second language, do you find it helps your writing? Do you have other reasons or benefits beside the ones I listed?

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.

What I learned from my pattern recognition talk at STC12

My session on pattern recognition for technical communicators was a very rewarding experience which taught me a lot. I thank Paul Mueller, Conference Manager, and Alyssa Fox, Program Committee Chair, for inviting me to speak, even though this was my first summit. Their friendly, indefatigable support set the tone for a high-energy, well-run conference.

If you want to revisit the session, here are the slides and the article from the proceedings. (If you haven’t attended the session, the article will probably be more helpful, for reasons explained below.)

Here’s a look behind the scenes of my talk and what I learned:

Two different roles

Attending a conference is not the same as speaking at one. Well, duh…

But what I mean is this: I took care to be an observant attendee before my own session, so I could gauge expectations and behaviors of attendees. Bluntly put: As attendee, I want my money’s worth. As speaker, I need to give my audience their money’s worth. Observing and knowing the first helped me achieve the second – or so I hope.

When I was still in academia, I was often put off by conference presenters whose ignorance of the audience’s interests and demands could be quite arrogant – and usually didn’t help the conference as a whole, either. So I wanted to avoid that.

Plus, one of the mantras of technical communicators is: “Know your audience!” How could I afford to ignore it at a tech comm conference?

“Unusual” works

I was unsure about my topic, because it was a bit unusual and off-the-wall: Tying the psychology of perception to technical communications – only to confirm what we do anyway, such as topic-based authoring and parallelism?

Me presenting on pattern recognition at STC12

(Photo courtesy of Jamie Gillenwater)

On the other hand, I know from attending previous conferences, how much I enjoyed and benefitted from such sessions. A-ha moments are fun and enlightening, they work in TV science programs, so maybe they’ll work at a conference as well…

During the session, I was too busy to count heads, but I’m guessing I might have had an audience of 70 people maybe. There were other sessions to choose from. Or breakfast, since I was in the 8:30 slot. So I decided early on to get over my worries and trust in the general curiosity of tech writers. 🙂

Rehearsing pays

So practicing helps… Again: Well, duh…

Specifically, it allowed me to move beyond bullet points. I’ve seen many a session (less so at the summit) where presenters mainly read their slides. To me, those are usually not the best presentations. I don’t need great showmanship, but reading the slides seems as if the speaker serves the slides rather than vice versa.

I’ve tried to make at least the a-ha moments less reliant on words and bullet lists and more like an illustrated story. And I’ve found that decent images will remind me of the story just fine. (The last section about actually applying pattern recognition in tech comm has more bullet lists, so people could take notes.)

In addition, I found that rehearsing also helps me to “know time” (a pet obsession of mine; I even have a blog post about it). I’ve seen excellent presentations, but it peeves me a bit if they take up 58 of 60 minutes. I also learn by asking questions and by engaging with the speaker or others in the audience. And to me, it seems a bit careless to mar an excellent session by running overtime.

Budget your energy

I am really glad (and almost a little proud) that we’ve had such a lively, engaging discussion after my presentation. People suggested additional sources, propped up some of my arguments and ran with others, bringing up evolution, Edward Tufte’s information graphics and – privately afterwards – even Immanuel Kant!

My one regret is that by that time I was a bit exhausted and didn’t always do justice when repeating the question or comment for everybody in the room and for the recording. Not sure how I can achieve it, but I want to save not only time, but also energy to facilitate the discussion afterwards.

But all in all I think the session went well, I’ve really enjoyed the experience and am glad to contibute to our curious, friendly and supportive tech comm community!

Find out how users use your documentation

Asking good questions of your users is essential to know how your customers use your documentation. This is part 2 after my post about using a survey to get to know your audience. The introductory paragraphs are identical to last week’s post, so feel free to skip ahead to the two paragraphs before the next heading.

A recent thread at Technical Writing World got me thinking about user surveys and revisiting two posts from 2010 where I wrote about obvious, but not so helpful questions and how to segment users and survey your documentation.

You can get all kinds of answers from your users, but depending on your questions, I find some answers more helpful than others. Jakob Nielsen’s position about usability makes a lot of sense to me:

Pay attention to what users do, not what they say. Self-reported claims are unreliable, as are user speculations about future behavior.

But if we cannot observe users, we have to rely on what they say – and try to ask them questions which yield useful answers. If you include an odd number of set answers in your survey, you can slice up the results (instead of having to deal with freewheeling answers), and users have a chance to select the option in the middle if they want to.

– Here are some questions that can help you to find out how successful your documentation is. Note that it doesn’t simply ask customers what they want. Instead, the questions can help you to determine which deliverables and which topic types (such as concepts and procedures) need improvement.

There are obviously other and better ways to determine user behavior, from usage analytics to user-generated content – but many technical writers don’t have the mandate or means to simply use them. These ideas are for them.

How do you use the documentation?

Do you use the documentation…

  • To set up & configure <our product>
  • To operate <our product>
  • To learn about the business
  • Not at all

When you need help, where do you normally seek information?

  • I look in <product> online help
  • I look in <product> user manuals
  • I ask a colleague
  • I call customer services
  • Other

How frequently do you use <our product> online help?

  • Daily
  • A few times a week
  • A few times a month
  • Once a month or less
  • Never

How frequently do you use <our product> user manuals?

  • Daily
  • A few times a week
  • A few times a month
  • Once a month or less
  • Never

How successful are you with the documentation?

Can you find the information you need in the documentation quickly and easily?

  • No, not at all.
  • More or less.
  • Yes, very much so.

Is the documentation that you find accurate and complete?

  • No, not at all. | More or less. | Yes, very much so.

Is the documentation clear and easy to understand?

  • No, not at all. | More or less. | Yes, very much so.

Does the documentation help you achieve your task?

  • No, not at all. | More or less. | Yes, very much so.

Does the documentation provide sufficient theoretical and business background?

  • No, not at all. | More or less. | Yes, very much so.

Are you satisfied overall with <our product>’s documentation?

  • No, not at all. | More or less. | Yes, very much so.

Your turn

Which questions do you use to find out whether your documentation hits the spot? Feel free to leave a comment.