Rate and improve tech comm with the Net Promoter Score

You can use the Net Promoter Score to rate and improve technical communication – but it works best on the scale of corporate content for which the score was designed. Here’s why and how.

The Net Promoter Score (NPS)

The Net Promoter Score measures customer loyalty and satisfaction with a company or offering.  It boils down difficult issues with perceived quality to a simple question:

How likely are you to recommend our company/product/service to your friends and colleagues?

Usually, the answers are ranked on a scale from 1 (highly unlikely) to 10 (very likely). You distinguish the percentage of respondents in three groups:














  • Detractors are people who replied with 6 or lower.
  • Passives are people who rated your offer as 7 or 8.
  • Promoters are people who answered 9 or 10.

The NPS is the percentage of promoters minus the percentage of detractors: If 20% of your customers are promoters who really like your offering (and answered 9 or 10) and 30% don’t think too highly of it (and answered 6 or lower), then your NPS is 20-30 = -10. Generally, an NPS  above zero, indicating more promoters than detractors, is considered a good thing…

NPS for tech comm?

So how can we apply that score to tech comm? Are customers loyal to a help system? Are they likely to recommend it to friends or colleagues? Probably not in isolation of the described product.

There don’t seem to be a lot of ideas “out there” that connect NPS to documentation, but one article by JoAnn Hackos does: Influencing the Bottom Line: Using Information Architecture to Effect Business Success.

The key to turning the NPS into a useful tool for documentation is to take the scope from the NPS, not from the documentation! Hackos shows how we can relate the NPS to corporate and product content as a whole. This includes tech comm, but also marketing and sales content. This is what drives the customer experience which the NPS reflects. And it takes improvements in the corporate-wide content and its information architecture to increase the NPS.

Hackos describes a company which found that content contributed to the low NPS:

… senior management became advocates for significantly improving content quality. That meant changing the relationship between the technical authors and the product developers, requiring that information architects establish close relationships with customer support and training, and redefining the type of content that would be delivered to customers in the future.

– Sometimes, tech comm can adopt management tools to their purpose and scope, but with the NPS it seems most feasible to plug in to the corporate use of the tool.

Does this make sense? Can tech comm benefit from NPS and improvement initiatives? Or is that a hare-brained idea, and we should really stick to key performance indicators suitable for tech comm?

DITA with confidence (DITA Best Practices book review)

I recommend DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt to anyone who looks for practical guidance with DITA or topic-based writing with a future DITA option. (This book review has appeared in the Summer 2012 issue of ISTC’s Communicator magazine on p. 57 in different format.)

Cover of the DITA Best Practices book

The DITA bookshelf has been growing slowly but surely. Thanks to the recent addition of the seminal DITA Best Practices, you can now find most information you need for a DITA implementation project in one book or the other.

The paperback comes from IBM Press which has also given technical writers Developing Quality Technical Information by Gretchen Hargis, et al. If you know that recommended title, you will enjoy the same usefulness and clear layout in this new book.

Starting with topics

DITA Best Practices addresses the practical concerns of writers, editors and architects of DITA content in three well-structured parts. The first part on writing starts with a chapter on topic-based writing and task orientation as two methods underlying DITA. The authors give clear instructions and guidelines for both methods. A generous amount of tips, best practices and ‘watch out’ warnings add the voice of the experienced practitioner which help to keep you on track or avoid beginner’s mistakes. The fictional ‘Exprezzoh 9000N’ coffeemaker is used consistently throughout the book to illustrate tasks and topics. Explanations why and how the methods work give writers the motivation to apply the advice with confidence. The chapter ends with a concise wrap-up section of the big points and a checklist to ensure you apply these big points in your work.

I have outlined the first chapter in such detail, because its clear and competent combination of elements — instructions, tips and warnings, examples, motivation, wrap-up and checklists — make this book so useful throughout.

One chapter each is then dedicated to topic types task, concept and reference. Each chapter describes the characteristics and motivation for the topic type, followed by instructions and examples along the standard DITA topic structure. The task chapter, for example, proceeds from <title> via <shortdesc>, <context>, <prereq> to <steps>, etc. However, most guidelines, examples, tips and warnings apply to good topic-based writing practices in general.

A chapter dedicated to DITA’s ‘short description’ element with its multiple uses in topics, links and search results helps novices with the challenge to use this powerful element correctly.

DITA’s architecture explained

The second part of the book builds on the first. After describing topics as DITA’s most essential building blocks, the book focuses on making topics work together by connecting them and by expanding their usability.

Two chapters show you how to connect topics into a coherent output, such as an online help system or a book. The first chapter on DITA maps explains how to create tables of contents, including bookmaps for print publications. The second chapter on links describes the four different ways to link topics to each other that in DITA. In their reassuring style, the authors help you to distinguish them, so you understand when to use which link type and how to apply each correctly.

The next three chapters explain how to make topics work together by expanding their usability: You can use metadata to make your topics ‘smart’ by adding information such as index terms, addressed audience or described product or version. You can use conditional processing to customise output. And you can reuse content for more consistent output and reduced translation costs. A clear workflow helps you to determine which of your content you can reuse and how.

Editing in DITA

The third part of the book deals with editing. One chapter outlines the steps and decisions of a project to convert your exiting content to DITA. Useful worksheets help you to analyse your content and prepare it for conversion. The chapter on code review helps you to avoid or eliminate common problems that restrict the benefit of your DITA code. Based on their experience, the authors remind you to use DITA topic types and elements correctly, for example, to use the <steps> element in task topics instead of a more generic ordered list. The chapter on content editing applies best practices of editing to DITA topics and maps.

Useful and recommended

Since it came out, I have used this book more than any other technical writing book, except a style guide. Had it been published earlier, it would have saved me many an uncertain moment when I was designing and teaching our information model. I especially appreciate the clarity, the concision and the well-argued advice of do’s and don’ts. For all its benefits, be aware that the book covers neither the DITA Open Toolkit nor DITA specialisations!

DITA Best Practices lives up to its subtitle and provides essential instruction and advice to technical writers, editors and information architects. Project managers will find it equally helpful but should also consider Julio Vazquez’ Practical DITA which reflects a project structure better. Decision-making managers are probably better off with Ann Rockley’s DITA 101 which gives a shorter high-level overview.

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?

Writing to create context to think – and work

The skill of technical communication is to create a context in which other people can work. – This concise insight helps me to stay focused on my users and their tasks, even if it’s not totally original.

I came to it via an article by Tim O’Reilly in his Financial Times article “Birth of the global mind” where he quoted Edwin Schlossberg:

The skill of writing is to create a context in which other people can think.


Proving the benefit of consistency in tech comm

To ensure efficiency and accessibility of technical communications, use consistent, common formatting, for example, for interface elements. What sounds obvious to many technical communicators is actually proven in academic studies. This post is for people looking for proof that consistency has a benefit in technical communications.

I’m taking my cue from a question that appeared in a LinkedIn group:

[I need to] find studies or tests that show that it is value-adding to have consistent formatting on e.g. User Interaction elements (such as buttons or handles) in your instructive documents. Can anyone share studies or tests in this area?

I can offer an answer on two levels:

  • The general benefits in terms of human perception
  • The particular benefits of consistent documentation

The neuroscience of consistency

Human perception favors consistency. The mind groups things easier, faster and with more confidence, if they’re consistent and have something in common.

Gestalt law of similarity illustrated

Gestalt law of similarity: The mind groups similar elements into collective entities, from Wikipedia.

Psychological studies have shown two principles by which human perception groups things: Proximity and similarity. For a comparison of these two principles and further references, see Han, S., Song, Y., et al. (2001). Neural substrates for visual perceptual grouping in humans. Psychophysiology, 38, 926-935. Han and colleagues actually quote several studies that “proximity is a more salient cue than similarity.”

In technical comunications texts, we usually can’t practically lump all names of windows or fields across all topics together to show they’re related.

But we can resort to similarity to help readers understand that we mean a GUI element at each occurrence. If we always write their names in bold, for example, readers will recognize that similarity across topics and learn to scan for it (whether they’re aware of it or not). If we always mark up GUI elements somehow, sometimes in bold, sometimes in italics, readers are more likely to wonder if the different markup has a meaning – and they won’t be able to scan the text as quickly and reliably.

For more psychological research and how it applies to technical communications, refer to Chris Atherton‘s excellent and accessible article “What and where?” in ISTC’s Communicator quarterly, Spring 2011, pp. 28-29.

Studies of applied consistency

So much for the theory. But does consistency, for example in formatting GUI elements, have an actual benefit in documentation?

One very good resource to argue for such consistency is the Research-Based Web Design & Usability Guidelines. This 292-page tome sets out “to provide quantified, peer-reviewed Web site design guidelines”. It was published by the US Department of Health and Human Services in 2006 and is available for free download, as a book and as individual chapters.

Chapter 11 on “Text Appearance” has a couple of applicable guidelines:

#2 Format common items consistently

Common, recurring items, such as telephone numbers, time records, button and window names should be formatted consistently, according to expert recommendations in: Ahlstrom, V. & Longo, K. (2001). Human factors design guide update (Report number DOT/FAA/CT-96/01): A revision to chapter 8 – computer human interface guidelines.

#4 Ensure visual consistency

Visual consistency, including the appearance of characters in interfaces, reduces user errors. “Studies found that tasks performed on more consistent interfaces resulted in (1) a reduction in task completion times; (2) a reduction in errors; (3) an increase in user satisfaction; and (4) a reduction in learning time.” The quoted studies include:

  • Adamson, P.J. & Wallace, F.L. (1997). A comparison between consistent and inconsistent graphical user interfaces. Jacksonville: University of Northern Florida, Department of Computer and Information Sciences.
  • Eberts, R.E. (1997). Cognitive modeling. In: G. Salvendy (ed.), Handbook of Human Factors and Ergonomics, 2nd ed., New York: John Wiley & Sons.
  • Ozok, A.A. & Salvendy, G. (2000). Measuring consistency of web page design and its effects on performance and satisfaction. Ergonomics, 43(4), 443-460.
  • Schneider, W., Dumais, S.T. & Shiffrin, R.M. (1984). Automatic and control processing and attention. Varieties of Attention. New York: Academic Press, 1-27.
  • Schneider, W. & Shiffrin, R.M. (1977). Controlled and automatic human information processing: detection, search and attention, Psychological Review, 84, 1-66.

Specifically, Ozok and Salvendy in 2000 confirmed the earlier studies that visually inconsistent interfaces lead users to poorer performance and more errors, see the summary in the Human Factors International newsletter.

– I hope this little field trip into academia can help you to prove that consistency not merely seems somehow desirable and logical, but has actually cognitive benefits proven in studies.

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.

A day in a tech writer’s life

In a typical day of my working life, writing takes a backseat to collaboration and communications. – This article first appeared as an “A day in the life” column in ISTC’s Communicator in the Spring 2011 issue, page 58. I really enjoy the “A day in the life” pieces, because they’re like chatting with fellow tech writers about their day at the office. So I was honored and proud to write one of the instalments, and I hope you enjoy it.

A day in the life

It’s an ordinary spring day, and I wake up in Frankfurt, Germany. When I’m lucky, the sun shines into my apartment to greet me. My morning routine is woefully brief, and I take a train to Bad Homburg shortly before 8am. The commute is pleasant since I live in the city, but work in the suburbs.

Frankfurt skyline, as seen from the Main river bank

Frankfurt skyline from the Main river bank

I’m a Senior Technical Writer for SimCorp, a Danish company that develops and markets the investment management system SimCorp Dimension to banks, insurance and fund companies.

I arrive at the office around 8:30am. I’m the only full-time writer in the German office, though a tester across the hall writes part-time. Ten writers are based in Copenhagen and Kiev.

I start up the PC and get a cup of tea. I receive an email from a colleague who has found an error in the online help. I check with the developer; my colleague is right. I check it against the Release Notes. This is embarrassing, they contain the same mistake, nobody had caught it. The Release Notes have gone out already, but at least I can correct the online help for the next release.

Next, I check the Solutions database, which is what we call our FAQ collection. We technical writers are responsible for editing the entries and aligning them with our documentation. A consultant has created an entry with a workaround. That’s odd: the Solutions entry does the trick, but we should really just fix that exception! I consult with the developer who will fix the bug. We will publish the Solutions entry for the time being and delete it in the next release.

It’s 9:30am, and my testing colleague asks for my opinion. She is about to finish her first manual and has created a list of index terms and wants my opinion on them. Also, the Word template for manuals has become corrupted somehow, so we need to fix the page headers, which are supposed to show chapter numbers, chapter headings and page numbers. Her index looks good, so we agree on it very quickly. Then we wrestle with Word for a while.

At 10am, it’s time for a video conference with the Copenhagen headquarters. I’m one of four people developing the future documentation strategy. We’ve already sketched out the processes on how we want to work in the future to implement structured and topic-based authoring.

Today, we discuss a design for an information model that I’ve drafted. I’ve basically taken a subset of DITA 1.1 and mapped its topic types and elements to our documentation contents. My colleagues have been reviewing it before the meeting, and they point out some parts that are inconsistent or confusing. Also, our model is still missing a couple of metatags, which means that my task until our next meeting will be to clarify some sections and to add the metatags. The video conference ends at noon, so I can catch my German colleagues as they head down to the cafeteria for lunch.

After lunch, I find an email by a colleague writer. I’ve agreed to review his manual, and here it is. The review is tricky since I don’t know a lot about the module he describes. SimCorp Dimension is a fairly large and complex wall-to-wall system, so not every writer knows all modules in detail.

We had agreed that he’ll need another reviewer for the actual contents, but I can still help him with the chunking of topics and the manual structure. I propose to change the nesting of topics in a couple of places. Also, the topic headings aren’t fully consistent yet. I hope he will find my suggestions helpful.

Reviewing the manual reminds me that I still need to find reviewers for my own manual that is just about finished. I can always count on the product manager (if he can find the time), but I like to have one of the implementation consultants review it as well. They know our customers and their workflows best from implementing the product on site, so their reality checks are invaluable.

At the same time, it’s often tricky to find someone who can spend one or two days away from a project. It helps that they find the manuals generally useful. I approach the team leader and tell him when the manual will be ready and that it will take 6 to 8 hours to review. He has a couple of colleagues in mind, but needs to check their schedules. He will get back to me.

It’s 3pm, and I start to actually write documentation. I continue to write Release Notes for the upcoming release. That means I go through all the development efforts in the tracking system and briefly document the enhancements and their benefits.

In between, I come across one enhancement where it is not clear yet whether it will actually be included in the upcoming release. I contact product management and, indeed, it’s not been decided yet. That makes me nervous: in the previous release, some of these decisions came awfully late and required some last-minute editing.

Though I started writing rather late, I make some good progress. Around 5pm, I call it a day and take the train home. When I’m lucky, I can see Frankfurt’s skyscrapers shimmer silver in the setting spring sun.

Your turn

How much time to do you spend writing, as opposed to communicating? Is this similar to what your days look like? Feel free to leave a comment.