Top 3 fixes when editing topics

A few recurring issues distinguish the editing of structured topics from that of other content. Here are the top 3 issues I’ve recently found while editing topics for language, consistency and structure.

1. Topic heading is weak

A heading can seem appropriate when you’re writing the topic, but it may still seem weak when you see it in the context of the entire help system, for example, in a list of search results.

Write topic headings so they give your readers a precise idea what that topic is about. Yes, that can be challenge when you’re trying to be precise and concise at the same time:

  • Indicate what kind of information a topic contains. For task topics, consider starting the heading with an imperative verb. For concept topics, consider using noun phrases.
  • Offer enough context so your reader can identify what area or functionality in the product the topic refers to.

2. Purpose or user benefit is missing

A topic can look great and complete: It does whatever self-contained thing it set out to explain. But if it doesn’t also contain a why and wherefore, it’s harder for the reader to understand whether they’ve come to the right topic and how it helps them.

Include the purpose or user benefit of whatever the topic describes early on, in the first or second paragraph. Answer the readers’ potential questions:

  • Why is it important to know about or do whatever the topic describes?
  • How does this connect to my work?
  • How does it make my job or my life easier?

Be careful to describe the purpose or benefit of the topic’s content, for example, the actual concept or task, not the purpose of the topic. Focus on: “This function helps you…”, not “This topic tells you…”

3. Topic mixes topic types

A topic can look complete, comprehensive, and self-contained, but if it goes overboard and describes both, functional tasks and underlying concepts at length, it tends to overtax the patience of those who only need to know one of the two. It also makes it harder to assign a clear heading, to structure the topic clearly and to reuse the topic in additional contexts you might not yet know about.

Stick (mainly) to one topic type per topic. If you’re using the traditional triad of concept, task and reference topics, divide them accordingly, but keep it pragmatic. Ray Gallon and Mark Baker have both shown how a little conceptual information in task topics can go a long way, but they shouldn’t replace entire concept topics. Also see my previous post When topics don’t quite work from two years ago.

Summary

These top 3 issues and several others basically have the same underlying reason: We tend to write topics in the context of a function or a window, but that context is not necessarily familiar or identifiable to our readers.

Issues with the same reason also share the same basic solution: We should focus on writing topics in the context of our readers, their environment and their tasks in it.

Obvious structure in tech comm benefits all users

Informational text that exposes its “structural information, such as hierarchical relations” gets high reading comprehension scores, whether readers have prior subject knowledge or not. This is the result of a study reported in Learning Solutions Magazine by Chris Atherton. And it’s good news for technical communication because it means structured writing and topic-based authoring done well benefit novice and expert users alike.

The study

The study presented a 5,000-word article in three formats to two different groups. The three formats were:

  • A linear document of paragraphs
  • A hierarchical set of linked topics which was basically web site six levels deep
  • A mixed format which combined linear text presentation with links to related topics that didn’t expose structure or hierarchy

The two groups of audience were:

  • Novices without prior knowledge of the subject
  • Experts who had formal training in the subject

The results

It’s best to scroll down to the results graph over at the magazine website, but in case that disappears, here’s a summary of the different reading comprehension scores:

  • Novices understood the hierarchical format best, closely followed by the mixed format, with the linear format a distant third.
  • Experts understood the linear format best, closely followed by the hierarchical format, with the mixed format a distant third.

So exposing the hierarchy and structure of the text benefits novices and experts alike. If you’re writing for experts only, presenting linear text gives them a slight advantage, but “shuts out” novices.

The implications for tech comm

  • Structure authoring helps your users understand and remember. Novice and expert users alike can make sense of the information not only from the individual bits and pieces, but also from the structure how everything hangs together. For example, consider relating concepts and sub-concepts to on another. Or when instructing users to do tasks, consider giving an overview of the big picture process first. Then break down the process clearly into distinct procedures and further into individual steps. For many readers, easy access to structure also helps them to retain information better, regardless how they manage to memorize it.
  • Structured authoring helps you to create complete documentation efficiently. You can organize and maintain your information more efficiently with structure and hierarchy. Structure makes it easier to ensure that each piece of information has a distinct place, so you can avoid redundancies. Hierarchies make it clear where your concepts and procedures are complete and where you still have gaps. It’s easier to note a missing topic or sub-chapter than a missing paragraph somewhere in linear text.
  • Limited advantage of linear text. The study showed that linear text in paragraphs is most comprehensible for expert readers. But I think the advantage of this format is in general limited:
    • For novices, linear text is a distant third, so relying on “linear” requires that you have a homogenously expert audience.
    • For you as a writer, linear text possibly takes more time or effort to maintain, depending on how much text you maintain and how often you update.
    • For other writers who need to edit or update your documentation, linear text is probably harder than topics that expose the internal structure of the subject matter.

By the way: Chris Atherton and I will lead a workshop together at TCUK13 in Bristol on 24 September. So if you’re in the area and want to “Bake your own taxonomy”, consider joining us. 🙂

TCUK13 early bird registration is a steal!

From now through 28 June, you can get an all-inclusive registration for TCUK 2013 on 24-26 September in Bristol at the members’ rate* for 560 GBP, that’s approx. 860 USD or 670 EUR. And I do mean all-inclusive! That rate includes

  • Tuesday of workshops, choose 2 of 6
  • Wednesday and Thursday of 2 dozen+ presentations in 3 streams
  • Tuesday and Wednesday nights’ bed and breakfast accommodation at the conference hotel
  • Gala Dinner on Wednesday evening
  • Dinner on Tuesday evening
  • Lunch and refreshments on all three days

* Members’ rate applies to members of the ISTC, of any TCeurope organisation or of STC (USA)! For non-members, early bird registration is 690 GBP, approx. 1,050 USD or 820 EUR.

But don’t delay – you must book and pay here before the end of June to qualify!

What I learned at the STC Summit 2013

Here are my lessons from the STC Summit 2013. This was my second summit after Chicago last year. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

Prepare to have your questions reframed! To me, this is one of the greatest benefits of a tech comm conference: You arrive with a question – and get it “more than answered”. I talked to someone who came to Atlanta trying to find the right tool and quickly started collecting different leads. Then one conversation in the hallway made her realize that she should first re-evaluate her processes and postpone the tool selection. By reframing her question away from the premature tool space, she’s now more confident she’ll come out with a more efficient solution than she could’ve gotten by merely switching tools.

Latch on to wider perspectives. There were several sessions dedicated to neighboring disciplines and approaches. I was happy to hear David Pogue’s keynote and Lee LeFever’s presentation address cognitive issues of tech comm which dovetailed nicely with my own session about semiotics and mental models. I don’t think any of this will revolutionize the way we do tech comm. But it’s an approach that helps us to understand how successful tech comm works and why. And it even complements other areas such as Information Architecture, as I found out when I compared notes with Alison Riley after our talks. There were also several sessions about data visualization that neatly complemented each other.

Lightning talks are great fun! Again, the summit had two sessions of lightning talks (5 minute talks with slides advancing automatically and mercilessly every 15 seconds). This is a great format because you can transport a lot of information in short time – and it’s fun to watch them go off the rails a bit when the slides run away from a stumbling, bumbling presenter. It’s all in good spirits, though: Everybody in the audience admires the courage of lightning talkers and would be just as scared of slipping up. But please, lightning talkers: Some of you can be a little more courageous and go for a bit more content. Don’t plan for dead air as you wait for the slide to change, just in case you slip up.

Standing room only at the second Lightning Talks session. Photo by ‏@StubbornlyWrite.

Standing room only at the second Lightning Talks session. Photo by ‏@StubbornlyWrite.

Progressions are difficult. I find progressions generally a difficult format (and I let the conference organizers know in the evaluation forms). For many topics, 20 minutes is awfully short for a stage-setting presentation and a discussion among the 6 to 10 attendees. One progression leader who succeeded admirably in my opinion is Roger Renteria. His progression on the benefits of volunteer opportunities was quick to set the stage and open to invite questions, comments and ideas from different angles! Another solution I’ve seen is to relegate much of the info to the handout, but that seemed less successful than Roger’s approach.

Choose sessions by title and speaker name. At previous conferences, I usually selected sessions to attend by the title and the description. Now as I’m familiar with several speakers, I find that I can select sessions just as reliably by speaker name. If I know and like someone’s work and perspective, whether from a blog or an article or a previous talk, I usually find it worth attending their session, even if I might not have selected it otherwise.

There are no stars. Okay, so some names loom larger in the tech comm space than others, especially in twitter and blogs. But I’ve found everybody really accessible and genuinely interested in tech comm at large. I just figure that if I’ve gone through the trouble to attend (as Atlanta is not the hometown for most of us), I might as well make the most of it. And rubbing shoulders and engaging with people whose work I admire is a great opportunity, whether it’s after a session, in the hallway or after-hours at the bar.

Welcome first-timers and students. I’ve seen some of the most enthusiastic reactions to sessions from students, graduates and first-time attendees. They often bring fresh ideas and new perspectives to our profession. Maybe some ideas are owing to youthful idealism. Still, we can all use their energy to make sure they become engaged and happy practitioners who can carry our community forward!

Go meet the vendors! I’ve found the vendors and exhibiting consultants genuinely interested, putting tech comm before sales. So I enjoyed getting acquainted and comparing notes with them, even if I’m not in the market for the products or services they offer. MadCap’s staff explained to me how to repair corrupted topics (I know – I shouldn’t corrupt them in the first place… 😉 )

@MadCapSoftware booth at the STC13 expo.

@MadCapSoftware booth at the STC13 expo.

Over at Adobe, Scott Abel was interviewing tech comm’ers about hot topics and pet peeves; look for the videos to come to Adobe’s blog.

@valswisher and @scottabel prepare for a video at Adobe's booth. Photo by @sarahokeefe.

@valswisher and @scottabel prepare for a video at Adobe’s booth. Photo by @sarahokeefe.

If you’ve been to the STC Summit, please share your insights in the comments. If you haven’t, feel free to ask whether it can deliver what you are hoping for. I’ll answer as best as I can.

STC13: Alyson Riley about effective IA

In her session “Building Effective IA Teams in Resource-Challenged Times”, Alyson Riley from IBM offered her take on the recent theme that tech comm needs to “speak business” to prove its worth. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

Alyson argued that “nice to have” initiatives are no longer compelling enough to get tech comm a budget or a mandate. To play a mission-critical role in a corporation, tech comm must plug into the corporate strategy. However, that strategy and its stakeholders usually isn’t waiting for us to put in our two cents. So we tech comm’ers must:

  1. Focus on corporate strategy as opposed to tactics.
  2. Play to the motivations behind the strategy, so we can come up with ways to support it with our unique skills and contributions.

The following moves can help with that second step:

  • Address the “buyer evaluates” and “buy” stages of the product. Usually, we speak to the “customer uses” stage of our product where there’s often more cost than income. The challenge is to make it compelling for buyers and sales to also use our content to their benefit in the more profitable stages. A good start is to ask sales: “What is the hardest part of your job?” and see if we can help them with the information we provide.
  • Influence social content to help leads along the marketing funnel from awareness to loyalty and advocacy. That doesn’t mean to “sell out” completely to marketing. It’s often as easy and sensible as including customer benefits in our content. Simply add the “why” to the “how” and give clients a chance to understand and promote your product.

Both moves boil down to the same principle: Don’t educate stakeholders in sales, marketing, product management, etc. about the product. Instead, imagine what the success of these respective stakeholders looks like and address that:

  1. Analyze opportunities your product can address in the terms of sales and marketing.
  2. Craft an effective story that centers on your content and how it can drive revenue, sales, customer satisfaction and loyalty.
  3. Prove it with metrics that speak to the stakeholders.

When it comes to metrics, page views of documentation usually don’t impress managers much. Instead, Alyson suggested “time-to-value” (TTV) which measures the customer’s time from buying or paying for the product to the moment they reap value from it. This is similar to “return-on-investment”, but TTV can be clearer to measure when investment consists of one-time payments plus maintenance fees. Also, it’s easier for tech comm to favorably influence TTV… 🙂

STC13: Lee LeFever on the art of explanation

Lee LeFever is the founder of CommonCraft, best known for the instructional videos with the drawn paper cut-outs that a hand moves around as a voice explains how stuff works. He presented their approach to explanation which focus on empathy with the audience to foster understanding. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

Explanations are hard and try as you might, they can still fail – as anyone knows who has given driving directions to a stranger and then seen them make the wrong turn.

The key to good explanations is empathy with the “explainee”, so you can explain something in their terms. What gets in the way is the “curse of knowledge” which means we cannot remember what it was like not to know how get to the specialty store or how a cloud service like twitter or dropbox works.

To show how explanations increase understanding, Lee used an explanation scale. First you have little understanding, and you care about the big idea, the “why?” Why should you care about a cloud service, why is this important to you? Once you have the “why?” down, you’re ready for basic understanding of the essentials, the “how”? How does a tool work, how can I use it to my benefit? To get expert understanding, you assemble more and more details for different scenarios – and before long, you have all the knowledge to explain this thing yourself!

Four features can make explanations successful:

Context anchors an explanation in shared experience and creates agreement. We all know what it feels like to have misplaced your keys, and we can agree that it’s very annoying. Context is important to show why something is relevant to you.

Story ties together a problem and its solution in a narrative arc. That can be as simple as: “Bob has a problem. Bob finds a solution. Bob is happy!” Story invites our empathy because we can identify with Bob and root for him. It illustrates facts, such as cause and effect, in real life.

Connections can provide a shortcut to other stories we already know. When the producers of the 1979 science fiction movie “Alien” sought funding, they connected their project to a recent successful movie in three simple words: “Jaws in Space”.

Analogies can emphasize “what’s really going on”. Consider an encounter with a bear and how it sets off your “fight-or-flight” impulse with stress hormones. Now transfer that experience: “Imagine the bear comes home from the bar every night.” This analogy gives you a good impression what it feels like to be the child or partner of an abusive alcoholic.

Lee closed by sharing several examples, both from his CommonCraft videos and elsewhere.

STC13: User Assistance, Tech Comm, and Learning

The session “User Assistance, Tech Comm, and Learning” brought together four seasoned professionals to discuss common grounds between tech comm and e-learning: Nicky Bleiel, who moderated, Kevin Siegel, Saul Carliner, and Matt Sullivan. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

The panel, moderated by Nicky Bleiel. Photo by @viqui_dill.

The panel, moderated by Nicky Bleiel. Photo by @viqui_dill.

Saul’s opening statement pointed out important differences between tech comm and training:

  • Tech comm doesn’t aim at information retention, but training does.
  • Tech comm’ers mainly create content, but trainers mainly teach, whether online or “in real life”.

Yet there are large overlaps between the disciplines and their practice, especially in “informal learning”, specifically, in the purpose, the content, and the consumer’s awareness of learning.

Kevin added further common values and features which both share:

  • Brevity in topics, in e-learning lessons (typically less than 5 minutes), or in a video (less than 2 minutes)
  • Step-by-step instructions in task topics and lessons
  • Direct address of the user as “you”

Matt explained how he focused on pragmatic information delivery where his single-sourcing workflow almost automatically combines “teaching and telling” in documents.

In the discussion that followed, the panelists addressed further aspects of that intersection of tech comm and training:

  • By emphasizing user action and tasks over functionality descriptions, you can offer resourceful users interactions and showing and telling to mix and match. However, exactly targeting your audience always precisely is usually not possible (neither in training nor in tech comm), so resist the temptation to “helicopter-parent” your learners.
  • That intersection works well with thought-through minimalism (which is not the same as writing in a concise manner).
  • Selecting the right channel and format can benefit both purposes, tech comm and training, tremendously, whether you choose videos or interactions or text.
  • Sample projects can be helpful to support and illustrate both,  learning and, to a lesser extent, documentation. They can be used as templates for a quick start to explore user scenarios. Personas are a great idea, too, but they’re of limited value as long as they don’t support the person(a)’s task.

In closing, the panelists pointed out that the focus of tech comm and e-learning alike is on people, not theories, methods or tools. In either domain, all users are different and many are extrinsically motivated by policy, law or certification to learn. So make it easy on them and keep them moving along swiftly.

STC13: David Pogue’s keynote spech

David Pogue, technology columnist for the New York Times, kicked off the STC Summit 2013 with his keynote. He looked back to his previous keynote at the 2009 summit and forward to what future developments in technology and materials science might bring. (This is part of my coverage of the STC Summit 2013 in Atlanta.)

Alan Houser, President of the STC, introduced him as the “most publicly visible technical communicator on the planet”. David started with a recap of his earlier address. He explained (again) how up to 2009, the acceleration in technological developments had led to a challenge and a paradox. The challenge concerns hardware where machines have become smaller and smaller, while our means to operate them, namely our fingers, have remained essentially the same size. The paradox occurs in software where companies often justify the most recent upgrade by piling on yet more new features – without necessarily having a good place to put them.

David Pogue delivering the keynote speech at the STC Summit 2013. Photo by Nitza Hauser.

Out of this challenge and this paradox comes the unexpected situation where a company such as Apple can achieve a competitive advantage by successfully eliminating features in a device such as the iPod. This cult of simplicity sells, and the product or service with fewer buttons win, whether it’s an iPad or the Google start search screen.

The reason why this works is psychological, says David: Achievements give us joy and make us feel that, yes, I can do this, and for this, I’m a good person. Conversely, not understanding how stuff or works or why stuff is so weird terrifies us.

Which brought David to Windows 8 and his task to write book for his “Missing Manual” series about the operating system. David made it clear that he appreciates much about Windows 8 – however, there are certain features that drive him crazy because they task him with documenting something that makes no sense – a feeling many tech comm’ers know well.

Specifically, Windows 8 presents two versions of many applications, two browsers, two e-mail clients, etc. – one in the GUI with tiles and one in the regular desktop. In the tiles GUI, there are no folders or files – and the control panel with system settings is only available via search.

Okay, so David decided to document the two GUIs in two separate parts of his book. Which raised the question how you call each GUI. The desktop is the desktop. But what is the GUI with tiles called? It started out as “Metro” until a German retail chain of the same name threaten to sue Microsoft. The “Modern UI” moniker was internal Microsoft lingo only. So David asked Microsoft directly. The GUI with tiles it turns out is called – “Windows 8”! As is the operating system in which the GUI with tiles and the desktop both live…

This didn’t make sense to David, so he invented the name “TileWorld” – and the name stuck! (… it does sound like a DIY store for bathrooms to me…)

David thought the main issue was the decision to combine the two GUIs. The common desktop is a more cumbersome but runs all applications and is known to most Windows users today. “TileWorld” has its advantages in a mobile tablet world, but is unsuitable for many uses such as drawing, spreadsheets, word processing, etc. – all these don’t work well with gestures on a large touchscreen on the desk in front of you.

The takeaway lesson David shared was: Terminology should be for clarity and to serve the reader.”

David ended his keynote to rousing applause as he regaled us to his very own version of the show tune “I Feel Pretty”, “Im On Twitter”.

Join me for “Mental models for tech comm” at STC 13

I’m proud and happy to be presenting at the STC Summit in Atlanta in a couple of weeks on meaning and mental models and how understanding them can help us in technical communication. If you’re attending the Summit, I invite you to join for me:

Addicted to meaning:
Mental models for technical communicators

Tue, May 7, 4:00 pm in room Hanover AB

My presentation will explore how “meaning” works in technical communications, why it fails and how you can create meaningful documentation. I will draw on the cognitive psychology of mental models and advances in user experience design to show why minimalism works, but FAQ’s don’t, and how to write for users without irritating them.

Being meaningful in technical communications is harder to measure than being correct, concise or consistent. However, it is just as essential: Understanding how and why communication is meaningful to users helps to create more effective documentation. Participants will get a deeper understanding and a fresh perspective on what makes communications meaningful.

Maning proceeds from information to knowledge.

You will learn:

  • What distinguishes data, information, and knowledge
  • How (technical) communication transmits meaning
  • What mental models are and how they shape the meaning that users create from documentation
  • How we are addicted to meaning
  • How to ensure your documentation is meaningful

It’s a G-rated session, so you don’t need any previous experience or knowledge of psychology – just a curiosity what makes us tick when we read and write documentation.

So treat yourself to a fun romp of aha moments in the last session slot of the day – hope to see you in Atlanta!

Techcomm lessons from UXcampCPH barcamp

Two big lessons I take away from attending last week’s UXcampCPH, Copenhagen’s “un-conference” on user experience, are:

  • Tech comm’ers and UX’ers can and should join forces because we have essentially the same goals.
  • Barcamps can be a fantastic alternative to conventional conferences.

While the 270 attendees were a mixed bunch, to be sure, I met only about a handful of technical communicators like myself. So what was it like to be a tech comm’er among hundreds of UX professionals, graphic designers, information architects, web designers, etc.?

Barcampers hanging out between sessions at Copenhagen's IT University; photo by @andersmn

Barcampers hanging out between sessions at Copenhagen’s IT University; photo by @andersmn

So close, and yet so far apart

I frequently heard the question: What does a technical communicator actually do? The answer “Write documentation” proved confusing because that meant to some the documentation of a UX project. “Writing user manuals and online help” was satisfactory, but apparently not an obvious answer…

That’s a pity because at heart UX and tech comm share a gommon goals: We both make products mean something to customers. We just do it in different ways: UX’ers design the actual experience. Tech comm’ers help the user along with additional instructional, background, and technical information, when necessary.

If tech comm’s user assistance is embedded in UX’s user interface we actually blur the boundary: User assistance can start with UX field labels and progressively disclose more documentation via tool tips to a full-blown help system.

We even have an external reason to join forces as we both occasionally suffer from similar misperceptions when it comes to the value we add. The varieties of our achievements often goes unnoticed outside our respective fields, as the cliché goes: “Everyone can draw / write…” 🙂

What makes a barcamp special?

A barcamp tries to avoid many of the hierarchical pitfalls of conventional conferences. It emphasizes participation and networking over listening and consumption. The general motto is “You are the barcamp” – and the program is built at the beginning of event when potential speakers pitch their ideas for sessions. Depending on the number of votes from attendees, speakers get a spot on the program.

At UXcampCPH, everybody got to speak: Of approximately 270 participants, there were only 16 pitchers for the 24 session slots. The event was a bit special in that they invited 3 keynote speakers – which often isn’t done at barcamps to stress the egalitarian, participatory vibe. But in Copenhagen, the keynotes worked well by bringing everyone onto the same page (see my previous post of session summaries).

UXcampCPH participants pitching their sessions; photo by @JohannaBlomgren

UXcampCPH participants pitching their sessions; photo by @JohannaBlomgren

Here’s how I would compare features:

Conferences vs. Barcamps

  • Primary tool: Laptop vs. iPhone
  • Communication artefact: Business cards vs. twitter handle
  • Networking over drinks opportunity: Drinks reception vs. pitchers of beer
  • Food: Banquet buffet vs. organic soup kitchen
  • Location: Conference hotel/convention center vs. university lecture halls
  • Sponsors’ presence: Trade exhibition vs. brand exposure via room names & swag

If you know more reasons why tech comm and UX should join forces – or what distinguishes barcamps from conferences – feel free to leave a comment!