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.

Advertisements

Find more tech comm blogs

If you enjoy this blog, you can find more reading like it on the list of “20 Helpful Blogs for Technical Writing Students” put together by the folks at onlinecolleges.net.

The list contains many of the blogs on my own blog roll, and it’s short and concise enough so you can quickly pick up a couple of new sites for your feed reader.

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.

Get ahead as a lone tech writer with a STC webinar

A compact 1-hour STC webinar gives you the low-down about getting ahead as a lone writer, from tools to strategy – plus two words every lone writer should know how to use.

What?

Writers are often the only person in a company who create and maintain documentation. Lone writers who operate without a dedicated budget or specific managerial guidance find it hard to excel in their work. In this webinar, I will draw on my experience and explain how to make the most of this “benign neglect”:

  • Develop your skills—and your career
  • Raise your profile with management and colleagues
  • Contribute to a corporate communication strategy
  • Help your company to turn documentation from a cost center into assets

When?

Wednesday, 29 February 2012, wherever you are, right at your PC via the web:

  • 10:00-11:00 PST – Los Angeles
  • 11:00-12 noon MST – Denver
  • 12:00-1:00 pm CST – Chicago
  • 1:00-2:00 pm EST – New York City
  • 18:00-19:00 GMT – London, Dublin
  • 19:00-20:00 CET – Copenhagen, Berlin, Paris, Rome
  • 23:30-0:30 IST – Mumbai, Bangalore

How?

Available as webinar, live or recorded, via the STC’s webinar site:

  • STC student members: US$ 29
  • STC members, sale price: US$ 59
  • Not yet STC members: US$ 149

I hope to see you there!

Is the new Microsoft Manual of Style for you?

The 4th edition of the Microsoft Manual of Style (MMoS) has been updated substantially in a few crucial areas. It’s indispensable, if you work in a Microsoft domain and worth checking out if not.

Full disclosure: I’ve received a free review copy.

The previous edition of 2004 was becoming quite dated, so a new edition was eagerly awaited by many writers. Here’s what’s new, so you can make up your mind whether you need the new edition. I’ll focus on the first half, the “General Topics” with guidelines, which has the most significant updates.

General impressions

Guidelines have been reshuffled to emphasize the book’s shift from technical publications (such as online help or user manuals) to professional technical communications (which may also appear in web sites, blogs or wikis):

  • Previously, the first two chapters were dedicated to “Documenting the User Interface” with screens, dialogs, properties, etc. and to layout. So the message was: “Put proper words pretty on a page.”
  • Now it’s the “Microsoft style and voice”, followed by “Content for the Web”. So the new message is: “Know your audience and adapt your sound and your channel!”

Many guidelines and examples have been carried over or edited only slightly from the previous edition, which is fine, because they still apply.

Examples have adopted a new tone: Previously, they were marked as “Correct” or “Incorrect”, now they’re labelled “Microsoft style” or “Not Microsoft style”. Ironically, this modesty is undercut by another change in the text. Previous suggestions to “avoid” certain things have become more strict and now tell you “do not use”.

Layout feels fresher throughout and easier to read. See for yourself at amazon’s Look inside preview.

Cover of the Microsoft Manual of Style, 4th edition

The 4th edition by chapters

Ch. 1: Microsoft style and voice

A front-loaded new section presents 9 pages of “Principles of Microsoft style” along the lines of consistency, attitude, language, precision, sentence structure and grammatical choices, punctuation, contractions, and colloquialisms and idioms.

This is a welcome framework that can double as a declaration of values or truths to be held self-evident. A tech writing team I know uses the MMoS as the background for their in-house style guide – and with this new section, I guess they can get rid of some of the painfully argued standards and simply refer to this new edition.

I see this section not as a dictate by Microsoft, but as a modest proposal that’s worth considering – and discarding only with good reason. The book’s Look inside at amazon.com allows you to preview most of the chapter, so check it out to see what I’m talking about.

Ch. 2: Content for the web

This important chapter has also been rewritten and moved to the front where it has the prominent position it deserves. But to be honest, it trails several more focused, more expert works.

Still, this is now much more oriented towards useful content and starts with “Make the right content choices” and then goes on to advocate scannable, organized text with lots of links. Additional, but short sections address video, blogs, and wikis as well as task analysis, SEO and social media optimization.

So it’s now a decent attempt with helpful suggestions in the context of a style guide. If you’re at all serious about writing for an audience on the web, you will know or want some of the more expert titles.

Ch. 3: Content for a worldwide audience

This chapter has been edited and expanded, but not substantially changed from the previous chapter 3 “Global Content”. You can preview it, along with the new 2-column layout of guidelines and more information, as a sample chapter at Microsoft Press’ blog post.

Ch. 4: Accessible content

As the audience of technical communications has grown and diversified, accessibility has rightfully gained traction. So it’s a pity to see that this important topic still only gets 4 pages, and not much that’s new to boot.

This is little more than a first check list to make you aware of essential issues and remedies. You can find more in-depth information online.

Ch. 5: The user interface

This is the centerpiece of the manual – and essentially the law in what user interface stuff is called in the Microsoft universe. It’s where the new edition excels and the previous edition was most badly dated.

Much of this chapter had to be redone completely to include ribbons, smart phones, the MS Office 2010 “backstage view” (which is what the File menu section is now called that has replaced the application button). If you’re writing for any Microsoft product, including Windows, you will need this sooner or later.

Ch. 6: Procedures and technical content

This chapter has also been updated:

  • Cloud computing is in.
  • Guidelines for procedures, reference, XML and HTML  documentation remain.
  • Standards on documenting COM and ActiveX are out.

Ch. 7: Practical issues of style

This chapter now combines parts of what used to be chapters on “Content Formatting and Layout” and “Common Style Problems”. It contains essentially unchanged information about cross references, dates, numbers, page layout, titles & headings, etc.

Ch. 8: Grammar

A welcome addition to this chapter are several “international considerations”! If you’re writing for translation or an international audience, you’ll find these tips helpful, such as:

  • Avoid passive, because it translates poorly into some languages.
  • Avoid imperative in marketing tag lines which comes across as dictatorial in some cultures.
  • Avoid “(s)” for optional plural which translates poorly.

Ch. 9ff.

There have been few changes or updates to the remaining chapters on Punctuation, Indexes and keywords, and Acronyms and other abbreviations.

The verdict

The Microsoft Manual of Styles is a very helpful resource. It’s mainly well thought out and solves many problems, so you don’t have to.

If you write for Microsoft environments at all, you need this latest edition to stay consistent.

If you write for the web, accessibility, localization, international audiences, API/SDK documentation, you may need additional resources, either as online or print resources. The MMoS won’t – and in all fairness: can’t – deliver everything you need.

Half-way DITA: Why some is better than none

If DITA seems like a good idea, but you cannot make the case for it, you can move towards structured writing and make your documentation “future-proof” by meeting the standard half-way.

At the company I work for, we tech writers created manuals in parallel, but separate to online help. Over time, this gave us a documentation set that was inconsistent in places and hard to maintain to boot. Topic-based authoring which reuses topics in print and online can fix that, of course.

First, a documentation standard

Deciding on the method is one thing, but we also wanted a consistent structure that made the documentation easier and clearer to use – and easier to maintain for us writers. That required a model that specifies which kinds of topics we want to offer, how these topics are structured inside and how they relate to one another.

As we looked towards a documentation standard, we had two options:

  • We could create a content inventory of our documentation, analyse and segment it to tease some structure from that.
  • Or we could rely that others had solved a similar problem before and see if we can’t use the wheel someone else had already invented.

Turns out the second option was quite feasible: The DITA 1.2 specification gives us about all the structure we need – and more. We left out the parts we didn’t need (for example, some of the more intricate metadata for printed books) and adopted a kind of DITA 1.2 “light” as our information model.

Second, the tools

Note that I haven’t mentioned any systems or tools so far! Even though it happened in parallel to the rolling out topic-based authoring as our method and DITA light as our information model, the tool selection was mainly driven by our requirements on documentation workflows, structure, deliverables, and budget.

The tool that suited us best turned out to be MadCap Flare – even though it doesn’t create or validate DITA!

Using our information model in Flare, we believe we get most of the benefits of DITA – and considerable improvement over our less-than-structured legacy content. And speaking to people at WritersUA 2011, it seems that we’re not the only one to move from less-than-structured writing to XML and something “close to DITA”.

Technically, we’ve defined the DITA elements we need as divs in the Flare stylesheets, but otherwise use the straight Flare authoring-to-publishing workflow. Flare is agnostic to whether a topic complies with DITA, is somehow structured but not complying or totally unstructured.

The benefits of DITA, half-way

To us tech writers, the largest benefit of DITA, half-way, is that we can actually do it. We could not have gotten away with DITA, the full monty, which would have required a much longer project, a much bigger migration effort and hence, uncertain ROI.

For new topics, we are committed to writing them structured, so they follow the information model. To migrate legacy topics, we’ll have to ensure they have an identifiable topic type and a suitable heading, but we can cleaning up their insides in a “soft fade”, moving them towards structure one by one. This gives us a quicker win than cleaning up literally thousands of topics before having anything to show in the new method, model or system.

So we will have been working in Flare and with our home-grown information model for a long while, before all topics actually comply with the model. But then we will have a documentation set which we can feasibly move into real structure, whether we opt for DITA or some other XML-based CMS, with or without a CMS.

This post is an elaboration of a comment thread on the “Why DITA?” guest post on Keith Soltys’ Core Dump 2.0 blog.