A user survey helps you to know your audience

Asking good questions of your users is essential to know the audience of your documentation.

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.

Find out who your users are

If you write for different markets, audiences or countries, it’s important to distinguish user profiles and their answers. It will help you understand the answers in context of questions such as the following.

Which edition/version of <products> do you use most (please select only one)?

  • Users of “smaller” editions judge your product and company by the help they need from the documentation: If they get started quickly and find information easily, they will be more likely to recommend your product and upgrade to “bigger” editions.
  • Make sure you assign feedback correctly and don’t mistake criticism of older versions for feedback on your more recent efforts.

For how long have you worked in the industry? <or:> For how long have you worked with <products like ours>?

  • In B2B markets, novices might need more conceptual help than seasoned pros.
  • Experienced users can often offer more qualified feedback of your documentation in comparison to that of competitors.

For how long have you worked with <our product>?

  • Novice users rely more frequently on “Getting started” documentation
  • Experienced users can offer more reliable feedback on reference documentation.
  • Experienced users (especially if they are loud or many) require a comfortable change path when product usability changes. Remember the opposition to Microsoft Office 2007 ribbons by heavy users of previous versions.

How frequently do you use <our product>?

  • Infrequent users probably rely more on finding more basic information – and finding it again.
  • Frequent users may need more detailed information.

– What other questions should we ask about our users to ensure we put their answers into the right context? Please leave a comment.

Tech comm meets content strategy, with Ray Gallon

Technical communications and content strategy have a lot to say to each other.  Bloggers have frequently related the two disciplines. Tech comm conferences run streams on content strategy, for example, tekom11 dedicated a whole day to the topic.

Content strategy for software development

Ray Gallon at tekom. Photo by @umpff, used with permission.

Ray Gallon at tekom. Photo by @umpff, used with permission.

Leave it to Scriptorium and their excellent webinars to shed some light on the situation. Recently, they invited Ray Gallon to present his “Content Strategy for Software Development“. (To learn more about Ray, read his recent interview over at the Firehead blog. Or you can check out the very similar presentation which Ray held at tekom.)

Ray’s presentation was very enlightening to me, because he applied content strategy to software development. I create documentation for software applications, so I can relate to creating content for them. In the following, I’ll mainly focus on the first half, but I recommend watching the entire webinar.

Software development as information-rich environment

For the sake of his argument, Ray set the stage by looking at (complex) software developments not as products or tools, but as information-rich interactive environments. Software could thus be an expert system that supports users to make an appropriate decision, e.g., a medical diagnosis.

The first question to content strategists is then: What does the user need from the software? There are several answers; the user may need to

  • Know something (relating to concept topics)
  • Do something (relating to task topics)
  • Explore or understand something
  • Integrate or combine the software with his other tasks and processes

Plan to help your users

Ray then presented several document types which help content strategists to plan how they can best support users in their tasks and decisions. Among them was the Content Requirements Worksheet:

Ray Gallon's Content Requirements Worksheet

Ray Gallon's Content Requirements Worksheet explained. Click to enlarge. (Pardon the mediocre quality; prezi > WebEx recording > SlideShare is one compression too many...)

This document was a real-eye opener for me. It represents a holistic view of all user-facing content in a software application:

  • Informational, editorial content
  • Structural software content, such as user interface messages
  • User guidance, such as tool tips, help screens
  • User decision support to help users do the right things for the right reasons
  • Dynamic content, such as search results
  • Live interactive content as preesented in forums and social networks

Content workers, unite!

The Content Requirements Worksheet can be very beneficial to future users of a software. But it presents a challenge to content strategists to get a wide variety of requirements right. That is the opportunity for technical communicators and user experience designers and information architects to pool their skills and join forces.

As Ray said in his comment to my previous post:

Many tech comms do a bit of, or a lot of, content strategy in their work, and if an organization has a content strategy then everyone, tech comms included, needs to understand it and be on board.

So let’s transcend the silos of our systems, their manifold features and the artefacts we’re used to creating. Let’s start with good, thoughtful design from which our users benefit.

Your turn

Is this a good way to relate content strategy to technical communications? Or do you know better ways? Feel free to leave a comment.

Join us for pattern recognition at TCUK

Dr. Chris Atherton and I will be premiering our exciting interdisciplinary presentation on “Pattern recognition for technical communicators” at the TCUK conference near Oxford next week. You can find the session abstract on the conference web site or review my previous post.

Logo of the Technical Communication UK conference

Join us for a fun whirlwind tour through human perception and find out how you can apply pattern recognition:

  • Make sense of unknown subject matter
  • Overcome tech writer’s block and start writing
  • Chunk topics and find reuse opportunities
  • Help your readers to
    • Orient themselves in your documentation
    • Grasp individual topics quickly
    • Get the most out of navigation aids

Extra bonus! You’ll learn about apophenia, a concept that gives you something to talk about at cocktail parties and ranks high on most international geek scales… 😉

No previous experience required! If you’re at the conference and can get yourself into the right room on Thursday, September 22, at 10 o’clock, you have all the tools on-board that you need!

Next week I’ll be blogging from the conference, so watch this space…

Framing tech comm: O’Reilly vs. Dangerfield

Technical communication is perceived in many different ways, some more constructive than others. Luckily, the framing of tech comm is the result of a dialogue/feedback loop, so we can help to shape how we come across.

Tim O’Reilly on the future

Consider Tim O’Reilly, quite a visionary technical communicator. He works to create “The Missing Manual for the Future“. O’Reilly explains it by quoting William Gibson: “The future is here, it is just not evenly distributed yet.” So we technical communicators can help to distribute the future evenly – a pretty noble mission to be on.

Or consider Kathy Sierra whose Kick Ass Curve taught me that my documentation can help users look good and suck less.

– Of course, just because I find cool quotes on the web doesn’t mean my work and I actually help to “distribute the future” (what does that really mean, anyway?) or help a single user suck less. But it’s the attitude that counts. These ideas inspire me. They give me a sense of the best I can aspire to with my documentation.

Rodney Dangerfield on respect

Photo by Jim Accordino, CC-BY-3.0 via Wikimedia Commons

Or consider these assessments:

  • “No one reads the documentation.”
  • “Nobody cares, but we gotta have it.”
  • “This manual is unusable.”

They seem to be rather common, I sometimes even hear them from tech communicators who graduated from RDSP, the “Rodney Dangerfield School of Professions”. The school is named for its patron saint and his motto “I don’t get no respect, I tell ya…“. RDSP graduates tend to accept criticism, when they hear it often enough, not when they find it fundamentally and immutably true.

Actually, it’s worth finding out in a customer survey how many people do read the documentation – and while you’re at it, try to find out how customers use it and what they expect to find it. Maybe only a few care, but if a company cares enough to do documentation at all, they might as well do it right – and yes, you can get documentation done right on the 80/20 rule. And a manual that’s deemed unusable can be made better and clearer.

Tech communicators on their work

Most of the time, my work speaks for itself. But sometimes it cannot stand up against prejudice and misguided judgements. Then it needs my help. I don’t mean making excuses about a late spec or a review that fell through. I mean moving the critic into the position of the generic customer who reads my documentation and finds it useful.

And when I engage with my readers, whether they are colleagues or customers, they are frequently surprised how much thought goes into my documentation. They marvel that

  • Documentation that offers less of a narrative is actually easier and faster to use in the majority of cases when customers look up specific questions.
  • Many users welcome the separation of concepts and procedures, because they read concepts just once, but need to refer to clear, bare-bones procedures repeatedly.
  • What has recently beefed up our marketing material is actually lifted verbatim from the documentation.
  • When they find a mistake, I can tell them immediately what I will do to fix it and when it will be rolled out to customers.

This dialogue/feedback loop gives my work the chance to earn respect by virtue of its benefits. And it allows me to follow the goals that O’Reilly and Sierra have inspired in me.

Your turn

What’s your experience? Does it work to enlighten colleagues and customers just how cool your documentation actually is? Does it help? Please leave a comment.

Keeping your documentation stakeholders happy

Don’t forget your stakeholders and their practices as you improve and change documentation. – That was the humbling lesson I learned (once again) as I presented our revamped documentation to non-tech comm colleagues.

Reporting on progress

The company I work for currently moves its documentation towards more structured writing and topic-based authoring. We’ve already rolled out redefined processes and several topic-based user manuals, so it was an opportunity to present to  non-tech comm colleagues what we’d done already, why and how we did it, and what else was in store. I talked about topic-based authoring and how it’s chunked, task-oriented, reusable, and independent of delivery format. Then I talked about the benefits and challenges:

  • For users, topic-based help can be updated more frequently, it is easier and faster to use online, though it breaks the narrative flow
  • For everyone working on our module, it means easier contributions
  • For the company, it allows to leverage* content after one-time migration efforts

* I know “leverage” is not a verb, but there were managers present who love the word… 🙂

I thought I was pretty clever for presenting how cool the new documentation was not primarily for writers, but for users, my colleagues and the company as a whole. And it did go over well on the whole. But there was…

The thing about trains

Person reading by a track in a railroad station

The most contentious issue turned out to be an unexpected use of the documentation: Current user manuals sometimes contain flowing prose walk-throughs of sample setups with many screenshots. When they are written well, they are nice to read. And allegedly users like to print out the PDF files and read them on the commuter train.

The problem of prose

There are several problems with the narrative manuals for users:

  • They are hard to use and search in, unless you want to know exactly the one thing they are describing.
  • Any sample setup is bound to miss what they need by a little or even a lot, because our product is highly configurable (you can even customize field names in windows).

There are problems for writers as well:

  • The prose is really hard to update when functions or processes change because the narrative flow may require small or large changes in several places.
  • The screenshots take longer to update and localize than mere text.

I gave these reasons, invited colleagues to check out the manuals done in the new fashion and cited survey findings that most of our users consult the documentation when they have a specific problem, though very few actually read manuals end-to-end.

But the ultimate lesson for me was that I could focus on our mission all I want, I also need to address the change with my stakeholders not only in rational terms, but also in terms of their habits and expectations.

Your turn

Do you think the customer is always right, even if he asks for documentation that is harder to maintain and harder to use in most cases? How can you promote change among stakeholders which you are sure will benefit everyone in the long run? Please leave a comment.

When redundancy is good: Online help navigation

Redundant navigation can help users find what they’re looking for.

Redundancy in documentation is usually bad: When you have the same content (in different words) in two places, you pay twice for localization – yet you probably only remember to update one of the items. So you risk inconsistencies, extra costs and general havoc.

Not so when it comes to navigation! Redundant navigation can offer your users different paths to get to the one place where they find what they need. The reason this works is because users want to do different things at different times in your help system. (See my earlier post “Top 10 things that users want to do in a help system“.)

Tom Johnson’s recent post got me thinking about this when he asked for “Examples of Help Systems that Provide Users with Multiple Entry Points?” His approach is a bit different, however, from what I have in mind. Tom thinks about “adding metadata to help topics so you can sort them into different arrangements for different audiences”.

My idea is to offer a few additional entry pages with layers of pointers to get users to the appropriate part of the help system quickly. Only some of the options require tags on topics.

Here’s a design I once did for the rather comprehensive online help navigation of an asset management system, we’re talking several thousand topics. (Click on the image for a larger version.)

Example for redundant navigation in complex online help system

The idea is that different personalities of users come to the help with different kinds of questions:

  • Some users focus on their roles and approach the system from that angle, whether they work in front, middle or back office of a bank or asset management company.
  • Other users focus on the task they need to execute – which in an asset management system can be boiled down to five main types of tasks.
  • And some users expect to find certain forms of documentation, such as release notes, tutorials, manuals.

Depending on your choice, you would get through 1 or 2 more selection screens until you wind up at a specific help topic. And you could take different paths to get to the same topic.

For example, if you wanted to set up a fund, you would need to get to the topic “Set up a fund definition”. Of course, you wouldn’t know that. But you could get there in various ways.

For example like this:

  1. I’m working in: Back Office
  2.  > Fund accounting
  3.  > I need to set up fund accounting
  4.  > Set up a fund definition

Or like this:

  1. I want to: Set up static data
  2.  > For a fund
  3.  > Set up a fund definition

Or like this:

  1. Show me: Tutorials
  2.  > How to set up SimCorp Dimension
  3.  > Fund accounting
  4.  > Set up a fund definition

So the idea is to anticipate some of the most common questions and approaches users have to the system and to make the right entry points easy to find. This does not to offer so many paths through the forest of topics as to confuse users, but only signposts to topics we expect every user will hit (as long he is using a particular module at all.

Your turn

Could you, would you use such a help portal that offered different paths or would you bypass it in favor of the tabel of contents on the left and the search? Do you know other help systems that use such a structure? Please leave a comment.

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.

How efficient is your documentation?

To gauge the efficiency of your documentation, consider the time spent to create it plus the time it takes to use it.

That’s the lesson I learned from applying Scott Berkun’s make vs. consume ratio to documentation. Scott’s idea is generally that it takes time A to create a tweet or a poem, a book or a movie, and time B to read or watch it. Scott relates the two measures and points out how you can easily consume in a few hours what authors and publishers, actors and movie people have spent months fabricating.

“make + consume” in documentation

When it comes to documentation, I think you can add both measures to gauge efficiency of documentation – though not its coverage or quality!

But just for time, I try to keep in mind these tactics:

  • Minimize the total time required for you to create your documentation and for customers to find, use and apply it.
  • Consider spending more time to make your documentation faster and easier to use, especially if you find that customers have trouble with it.
  • Consider spending less time with documentation tasks that do not help your customers in using the described product.

Of course, time isn’t the only yardstick. Accuracy, completeness, legal and contractual obligations are just some of the other factors.

Still, I’ve found “make+consume time” a useful benchmark to stay focused on what ultimately benefits the user and what doesn’t.

Further reading

If you’re concerned about documentation efficiency, you might also find earlier posts of interest:

Your turn

How do you gauge the efficiency of your documentation process and output? Can you credit your efforts towards making your documentation faster and easier to use? Please leave a comment.

Top 3 success factors in online help systems

Service speed as well as content’s structure and spacing are the top 3 factors that determine whether your online help system is successful. That’s the gist when I apply 7 of Cameron Chapman’s “10 Usability Tips Based on Research Studies” to online documentation.

Cameron’s post of September 15 looks at the numbers behind the usability of web sites and, as she writes, “some might surprise you and change your outlook on your current design processes”. And they underscore the importance of offering documentation that’s quick to find, understand and apply.

Speed

Speed is essential for online help success in two ways.

Write help content so it is fast and easy to skim and understand. Cameron mentions two studies by Jakob Nielsen:

  1. Users read only about 28% of the text on a web site, and the ratio decreases with the amount of text.
  2. Users follow an F-shaped pattern when skimming web sites. They start reading at the top left corner (in cultures which read left to right, top to bottom), skim key words along the line and move down the lines in that pattern.

To optimize your online help for such behavior, you can:

  • Use headings, bullet lists and parallelism to ensure that users read the “right” 28% of the text. These are the parts which orient readers and guide them to the solution of their question, and then the solution itself (and hopefully they read more than 28% of that page…)
  • Front-load your headings, list entries and paragraphs so readers get the gist from the beginning.  This quickly guides your readers and helps them in their F-shaped survey of your contents.

Power your server so  it is fast to load and display the online help. Cameron refers to a study for the Bing search engine which shows significant decreases in clicks and user satisfaction once load times exceed two seconds. I assume that online help servers meet with similar impatience: Just like a search engine, they are intermediary services which users consult when they really want to do something else.

So measure and ensure that your online help web server can offer users short loading times. This is especially crucial in multi-step rendering processes of dynamic content which involve first a database and then on-the-fly rendering in HTML + CSS.

Space

The spatial design of information is the second essential factor in the success of your online help.

Use white space to improve readability and reading comprehension. A study at Wichita State University found that users prefer text on web pages with margins and optimal leading (= vertical spacing between text lines). They also retain better what they have read.

“Don’t worry about ‘the fold’”, says Cameron. Contrary to popular belief, users do scroll and read below the ‘fold’ of the initially visible top part of a web page. Cameron points to studies by a web analytics company and design agency which conclude that there is no correlation between page length and the number of readers who scroll at least 90% to the bottom. Instead, users apparently scroll when they think it’s worth scrolling – which again emphasizes the content, its readability and usability.

Structure

The structure of topics and contents in your online help is the third essential factor.

Navigation beats search. Cameron cites two studies that found users prefer navigation and usually resort to search only after the navigation failed them. (I assume this differs for experienced users who know what they can expect from navigation and search respectively.)

So do your technical communications team and your users a favor and maintain a solid topic structure that writers and readers find worthwhile to use. A good topic structure is a map that orients users throughout the system and in context. By contrast, a search result merely shines a spotlight on the topic a reader may or may not need. In short: Don’t let your search bail out poor structure and bad navigation.

Related topics

Psychology & technical communication, Chris Atherton at TCUK

Technical communication benefits greatly from cross-pollination with related disciplines, such as cognitive psychology. That was my conclusion after the presentation “Everything you always wanted to know about psychology and technical communication … but were afraid to ask” by Chris Atherton (@finiteattention).

Chris is an applied cognitive psychologist and Senior Lecturer at the University of Central Lancashire. She has the rare ability to cut through the crap without shortchanging her subject or her audience. She makes Occam’s razor user-friendly, if you will.

Here are my top 3 insights from Chris’ presentation and how I find them applicable to technical communications:

1. Do your reader a favor and supply context

Context relates different pieces of contents. More specifically, it relates what users already know to what they need to learn right now as they read the help. For example, an essential setup procedure is not helping the user, if they don’t know where to set up stuff. Well-written headings and carefully arranged “related links” help users to establish context and to evaluate whether the content they found is relevant to them.

Context also means the “location” of pieces of content. That location can be in a book (for example, about half-way through), on a page or screen (near the top) or in an online table of contents, such as Word’s document map (a sub-topic on one of the first branches after the introduction). Note that all the examples are really vague. But as Chris says, “we remember the gist and location.” And that’s what we go by when we try to find content again.

By the way, Chris pointed to research by Jakob Nielsen who found that location still works on long pages that require vertical scrolling! Apparently, readers do scroll – and remember the general location of what they read.

(You might recognize these points about context as two of my Top 10 things that users want to do in a help system.)

2. Simultaneity implies causality

That means that we often understand two things happening at the same time to be related by cause and effect. In technical communications, this is most relevant to training videos and user interfaces. For example, two call-outs appearing at once will be assumed to be related somehow. Don’t let the user guess, instead:

  • Be careful to create logical sequences.
  • Avoid presenting alternatives or unrelated items at the same time – and if you do, ensure to label them clearly (which will hopefully clutter up your screen or script enough to convince you to break them apart…).

Another example where simultaneity implies causality is people who can turn off streetlights simply by walking past them – which brings us to:

3. Don’t waste time catering to dogmas

This is a tricky one: Some psychological concepts are generally accepted as facts. Yet they make many scientists gringe, because the numbers and the evidence just aren’t there. For example, Chris referred to substantial criticism that’s hacking away at the alleged foundations of individually preferred learning styles.

For me, as a non-scientist, that means that I can support different learning styles in my documentation if it’s done easily and with no or insignificant additional effort, but I won’t go out of my way.

From here on, it’s a sliding scale into the murky depths of psychobabble which is easier to decode and ridicule. To quote an example from an NLP website: “Use brain gym to calm, energise or reconnect right and left brain for improved concentration.” (Apparently, in most people, the left and right brain are successfully connected, regardless of the brain trouble they may believe to have…)

Your turn

Do you know of other insights from psychology that can benefit technical communications? Or do you want to share ideas or experiences with one of the ideas above? Feel free to leave a comment!