When tech comm does other teams’ work

Should documentation be expected to do the job of other teams and departments to make up for their shortcomings?

That was the essential question in an interesting conversation I once had with a fellow tech writer. It’s basically a twist on the general idea that you often have to pick two of the three: High quality, speed, low cost.

The writer said she had changed her way of writing user manuals to include fewer screenshots, because some of them were not essential to the described task, and they’re difficult to translate and update.

Less than efficient reuse

Her manager didn’t exactly appreciate her efforts to create similarly useful documentation more efficiently, but objected to the new manual. He asked her to use more screenshots as before, arguing they were necessary for three additional purposes of the manual:

• Sell the product – though dedicated sales materials are also available.
• Double as self-study training material – though training is also available.
• Make up for poor usability where the software isn’t so intuitive in some places.

She is totally capable of creating documentation that can also be used for these purposes. (Apparently, the company didn’t have a content strategy which easily allows to share contents between sales, training and documentation.) But it’s just difficult to do it all when she faces pressure to limit cost and throughput time at the same time.

Possible reactions

During the conversation, my position was that her company can’t reasonably expect her to make documentation more efficient while she continues to make up for other shortcomings. (This ties in with the “Two words every (lone) writer should know“, which are “Later” and “No”.)

Then I thought that maybe her manager doesn’t actually know which tasks an efficient technical writer does best (if you can even generalize that) and what to expect from the sales, marketing and training teams. In this case, it might even be an opportunity to clean up processes beyond just documentation (though this easily gets presumptuous).

Your turn

What do you think? Have you been expected to do things that got in the way of your efficiency and that were really the tasks of other teams? How can we writers deal with that? Any ideas? 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:

• How and why to estimate writing efforts
• Top strategies to embrace cost metrics
• Top 3 success factors in online help systems, one of which is speed

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 10 reasons for tech writers and trainers to collaborate

Technical writers can and should collaborate with trainers to offer customers a unified and cost-effective learning experience. Here are eight specific reasons why they should collaborate – and two why they cannot afford not to do it:

1. Same goal: Ensure that customers can set up and operate the product efficiently, effectively and confidently.
2. Same audience:  Customers, more specifically users of the product (who, in a corporate setting, may have made the decision to use it or not).
3. Same demands by that audience: Fill a knowledge gap, whether it’s large or small, conceptual or practical.
4. Similar deliverables: Conceptual and instructional/procedural information, possibly in different formats, such as training slides or handouts, user manuals or online help.
5. Cost-effective deliverables: Share text and images, use cases and examples.
6. Better coverage: Writers and trainers see the product and its users from different angle and can help avoid professional myopia.
7. Beneficial reviews: Writers and trainers who review each others work also learn about their own deliverables.
8. Satisfied customers: A unified learning experience increases user confidence, satisfaction with and trust in the product.

Companies where writers do not collaborate with trainers run a considerable risk:

1. Confused customers: Incoherent or even contradicting messages in documentation and training materials confuse and alienate users.
2. Lost business, potentially in three ways:
   • Bad reputation and bad impressions keep prospects from buying.
   • Bad learning experience keeps customers from continuing or returning to the product.
   • If you’re really big, external companies can take a bite out of your training or manual business.  This is harder to replicate and hence less likely if you offer one seamless learning experience.

Your turn

Have you considered or tried to collaborate with training? Has it been worthwhile? Can this be a first practical step towards content strategy? Please leave a comment.

Shape the hype cycle with tech comm

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

The hype cycle

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

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

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

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

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

Enter technical communication

So what does technical communications have to do with it?

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

There are two reasons why this works:

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

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

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

Your turn

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

Top 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

• “Do you know Time?“ about parallelism and writing for speed
• “Top 10 things users want to do in your help system“
• “What tech writers can learn from UX designers“

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!

Welcome to summer reruns, part 1

My blog and I are taking it a little easier towards the end of the summer.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a walk on the beach…

As we’re gearing up for the new season, here are some reruns from the last year or so.

Popular posts from my blog

Trends in technical communication 2010

This is one of my two most popular posts by far. With the help of several readers, we’re commenting on and discussing two trends from a Scriptorium webinar “Technical Commmunication Trends for 2010 and Beyond”. Sarah O’Keefe predicts that it will include content curation. And Ellis Pratt proposes that technical communications will soon also shape an emotional user experience. Incidentally, Ellis will speak on the same topic at TCUK, so go see him, if you have a chance!

Making it as a lone writer

This is the first post in a small series where I share lessons learned and best practices how lone writers can get ahead. Incidentally, I will speak on the same topic at TCUK, so come see me, if you have a chance!

Reading outside the tech writing box

I’ve found that reading helps my writing, even off-topic reading. Technology journalism works especially well for me. I share my favorite magazines and anthologies and link to five articles that you can read online.

Noteworthy posts from elsewhere

Speaking of reading around. If you want to read up on neighboring disciplines, I recommend these three excellent posts:

Complete Beginner’s Guide to Content Strategy

Complete Beginner’s Guide to Information Architecture

Standardized Approaches to Usability

What tech writers can learn from UX designers

We tech writers have a lot in common with user experience designers, really!

Even though we may step on each others turf occasionally, we share a common objective: Make customers and users successful with our products. Add the fact that our jobs combine creative challenges with restricted resources, our situations are structurally so similar that we can learn a lot from each other.

So if we technical communicators are serious about overcoming departmental silos with our contents, we should also pick up a few tricks from the guys and gals in the next room or cubicle…

Here are just some a few lessons I’ve learned from blogging UX designers that speak to us technical communicators as well. Incidentally, they are strategic and processual, but I’m sure we can also learn from their specific methods:

Doing stuff you weren’t hired to do? Keith LaFerriere’s “Why Did You Hire Me?” has some advice for you. It easily applies to technical writers who find themselves writing for marketing or editing and polishing anything from offers for sales to presentations for the exexcutive board. (All of these are fine, respectable tasks – but maybe they’re not what you excel at or where you see yourself going…)

Countering less than brilliant ideas which managers or customers may have about your work is the topic of Whitney Hess in “No One Nos: Learning to Say No to Bad Ideas“: “It is my job to put an end to bad design practices within an organization before I can make any progress on improving the lives of our customers.” Replace “design” with “documentation”, and you have yourself a mission. Whitney uses best practices and data to make her case and also shows just how to say “no”.

Winning your manager’s support to implement a new method, such as topic-based authoring, is essential, but difficult. Especially if the cost-benefit argument unexpectedly fails. In “Selling Usability to Your Manager“, David Travis recommends a more psychological approach to present salient benefits beyond the bottom line.

Getting buy-in for better processes across your company is the subject of a virtual panel discussion “Evangelizing UX Across an Entire Organization” written up by Janet M. Six. Designers and information architects weigh in with helpful advice, such as:

• “For different groups to embrace [it], those groups need to see the value in the process — not only for the organization as a whole, but for their particular role and discipline.”
• “Practitioners should reframe the issue by asking managers to support and enhance the ongoing satisfaction of the customer experience.”
• “The one clear finding that has come out of the entire UX movement is that focusing on your customers is the surest, most direct way for any company to make money.”

Realigning can be a good alternative to redesigning, as Cameron Moll explains in “Good Designers Redesign, Great Designers Realign“. The “Incessant Redesign” seems to afflict designers more often than technical communicators. Still, his basic idea also applies to documentation: “The desire to redesign is aesthetic-driven, while the desire to realign is purpose-driven.” There’s a place for either type of project; Cameron’s post helps you to make the right decision.

- What alliances with other departments have you found helpful? What methods and tricks have you learned from colleagues in design, training, customer support, etc.? Feel free to leave a comment!

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

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

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

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

1. Search

I know exactly what I’m looking for.

Offer useful search results. Duh…

2. Find (and find again)

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

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

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

3. Know their way

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

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

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

4. Browse (as in “shopping”)

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

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

5. Get advice

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

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

6. Recognize items

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

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

7. Compare

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

Offer a selection of related topics.

8. Ask a human

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

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

9. Share

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

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

10. Take stuff home

I’ll take this!

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

Your turn

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

Readability vs. usability in manuals

The new manual is harder to read – but easier to use.

This is the feedback a colleague tech writer got from one of his reviewers. The manual had previously had a lot of screenshots, so it was easy to follow along.

My colleague revamped it to use fewer screenshots, but more structured text. As a result, the new manual was deemed to be easier to navigate and more useful in a wider variety of use cases.

I thought the feedback is spot on: Unless I’m writing a tutorial where I specifically lead users by the hand, I’d always take usability over the sheer readability. Usability can ensure that users find it easy to navigate the manual and find the information that applies to their current need.