Describing or clarifying: How do we explain stuff?

So our company has an elevator pitch competition. The task is to explain in 30 seconds “What does our company do?”

The submissions indicate that “to explain” means different things to different people. To some, it means “to describe or summarise information”. To others, it means “to translate and clarify for others”.

The two meanings reach different audiences with different levels of success. Description and summary are best when you have a similar background and outlook as your audience. Translation and clarification are best to bridge differences between you and your audience. Such a difference could be much vs. little experience with a product or knowing how to set it up vs. having to use it every day. To bridge this difference, you have to put yourself into the users’ shoes and remember how it is not to know all the things you know now.

Technical communication skills, our experience when crafting content, and the way we can structure information let us excel in the translating and clarifying. And the better we know our audience, the better we are at it.

Developers and testers who contribute to user documentation frequently deliver very good descriptions – and technical communicators can help them by translating and clarifying them further, if necessary.

We often hear that “everybody can write”. But what it means is that many people can describe (and some don’t even do that very well) – but few can clarify as well as a technical communicator.

If the distinction between describing and clarifying resonates with you, I’m sure you can think of more examples.

Advertisement

Top 4 layers for your tech comm strategy

To show and increase the value of tech comm in your organization requires focus and priorities. That’s especially difficult in times of too many conflicting demands and not enough resources.

But you can adapt tried-and-proven business principles and tools to keep your tech comm efforts on the rails and contribute to larger business goals.

The 4 strategic layers

A solid business strategy framework has four aligned layers:

• Higher layers have very few abstract elements which give lasting, big-picture orientation. Aligned means they give direction and help to define lower layers.
• Lower layers have many concrete elements which give specific instructions. Aligned means their execution contributes to achieving higher layers.

Yes, it takes some time to formulate the four layers – but I find it’s a good investment in your future: You can decide and defend what tasks you prioritize and how you do them. And you can show how tech comm add value to the organisation as a whole.

Now let’s take a look at the elements of the four layers.

The mission (statement)

The mission is the organisation’s reason for being put into practice. The mission takes several years to accomplish, and it should not be changed or abandoned lightly. The mission is guided by a vision for a future goal.

The mission statement is defined as “a written declaration of an organisation’s core purpose and focus that normally remains unchanged over time.” The mission statement is one or two sentences that fit on a t-shirt which the people behind it can be proud to wear.

In the mission statement, the organisation explicitly or implicitly answers four questions:

1. Why are we here? What is the unique purpose we serve, the value we provide?
2. What do we do? What products and services do we offer to provide that value?
3. Who do we do it for? Who are our markets and audience?
4. How do we do it? What principles and values guide our efforts?

For example, IKEA says: Our mission is to offer “a wide range of well-designed, functional home furnishing products at prices so low that as many people as possible will be able to afford them.”

For more about mission statements for tech comm, see my earlier post Why you need a tech comm mission statement.

The vision

The vision is the organisation’s goal several years in the future. It answers the question where the organisation wants to go. It can motivate the people behind it to get out of bed in the morning. It guides the organisation’s mission through time. By pursuing the vision, the organisation can accomplish its mission and fulfill its purpose.

For example, IKEA says: “Our vision is to create a better everyday life for the many people.”

Strategic goals

Strategic goals describe self-contained efforts that have a distinct, measurable effect on the organisation’s business success. When reaching a strategic goal, the organisation usually can:

• Offer more efficient or effective products and services
• Translate the improvement directly into a customer benefit

Strategic goals are major advances towards accomplishing the mission. They take around a year to reach, or even longer.

Tactical initiatives

Tactical initiatives are measurable milestones or contributions to a strategic goal. They often take weeks or months to execute.

Operational tasks

Operational tasks are individual steps in tactical initiatives. They take days or weeks to finish. Policies and procedures, guidelines and standards guide the execution of tasks.

Snack-size tech comm videos from STC13

Scott Abel talked several tech comm speakers, bloggers and other luminaries into short videos at this spring’s STC Summit in Atlanta. The results are now available as Adobe Thought Leader Interviews at STC SUMMIT 2013. Most videos pack an interesting, usually well-argued insight into a minute or two. Taken together, they’re a good survey of topics and trends that were bounced around the Summit – and a perfect excuse to relive some of the #STC13 spirit!

Here are some of my favorites and what I like about them.

Sarah O’Keefe: Tech Communicators Need to Focus on the Business explains why tech comm’ers need to see how their content and their deliverables fit into the larger business schemes of their organization or client. It’s not exactly the first time Sarah has put out this message, but I consider this a recurring theme and one of the most urgent challenges for our profession.

Ann Rockley: The Benefits of Content Modeling shows how and why single-sourcing and content reuse requires prior planning. You need to model your content to ensure it comes out useful in the different formats. I appreciate Ann’s message that you not only need to do it, but you need to do it right.

Bernard Aschwanden: Benefits of Structured Authoring offers a primer on DITA and neatly sums up why the separation into concept, task and reference topics makes sense in a lot of cases. I like the video because it’s quite a feat to summarise both DITA and topic-based authoring in 2:40 minutes – and with examples to boot!

Rahel Bailie: Reclaiming Content Strategy urges tech comm’ers to reclaim the content strategy turf from the marketing people who may sell themselves better and know about writing copy, too – but we tech comm’ers can add the badly needed technicial knowledge as well. I cherish Rahel’s vote of confidence that we can and should reach out into this neighboring discipline!

Andrea Ames: It’s Not Your Mother’s Tech Comm Anymore argues that tech comm has to change and is in fact changing as users consume it in ever-developing context which makes tech comm’ers, and in fact users, too, the curators of documentation. I enjoy Andrea’s enthusiasm that blends “must do” and “can do” in most of what she does.

Oh, yeah, and then there’s my own 1:17 minutes of fame, ranting about tech comm’ers who wait for instructions and tasks. My point is basically: “Don’t Ask for a Mandate“, but rather prototype what content needs you find and let the solution sell itself. (I stand by my argument, though I don’t like my overzealous look of a young lawyer fearing to screw up his first court case… 🙂 )

But I highly recommend checking out the entire series of interviews, because they cover a wide variety of topics, technologies and tools!

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.

Why you need a tech comm mission statement

A mission statement for technical communication can help everyone in your company (or you and your customers) to stay on track in pursuit of a common goal of what your documentation can and should achieve.

Just like a corporate mission statement, a tech comm mission gives all parties who are involved with documentation direction and a common goal. It describes the purpose and benefit of the documentation and how it is achieved. It helps to define processes for creating the documentation as well as metrics whether the documentation is successful. If the mission is well-conceived, it guides documentation strategy without prescribing it.

For example, if you want to focus on usability and speed, a mission for your documentation could be: “Our product help answers any user question about product use in no more than three mouse-clicks.” Your strategy would then aim for a well-structured, easily navigable context-sensitive online help – with printed user manuals and closely tied in training materials taking a backseat.

A more comprehensive mission could be: “Our product help provides users with relevant product information at the right time in the right format.” This would set you on a quest to find out who your user types are, which product information is relevant for them and which formats it can be provided efficiently.

A mission statement in itself cannot be right or wrong. But it must be useful in several respects. Specifically, it must help:

• Your customers and users by guiding you to provide useful documentation.
• Your company externally to provide documentation which improves the perceived product quality.
• Your company internally to anchor the importance and function of documentation.
• You as technical communicators to make appropriate strategic decisions about documentation, for example, which users to address, which deliverables and processes to define, which methods and tools to apply.

What do you think? Is a mission statement for tech comm necessary? Or merely helpful? Or a vain attempt at putting on corporate airs when the writers should just buckle down and get the job done?

(Edit: The discussion continues in “Getting mileage from a tech comm mission statement“…)

Tech comm communities are people, not tools

There’s not a single social media tool or channel that’s the vital “one-size-fits-all” connection for our diverse tech comm community, but it’s their combination that lets us thrive, as I’ve learned last week.

On Thursday, a colleague and I ran into an obscure problem with review packages in our help authoring tool, MadCap Flare. We didn’t find a solution in Flare’s online help, so I reached out to a user forum.

Peer/user forums

MadCap Software Forums are provided by MadCap, but they’re run for and by the community of MadCap users. I first searched existing threads to see if someone had encountered the same problem before, without success. But I did find a thread where two days earlier two users, V. and M., had run into a similar problem that we had also encountered – and solved.

In the communal spirit of give-and-take, I outlined our solution. (The trick hinges on knowing that Flare’s review packages are really zip files which you can unpack and manipulate – if you know what you’re doing.) Then I posted our own query.

Within 24 hours, M. posted three replies:

1. To confirm that our solution indeed works, at least in some circumstances – hence we were on to something useful that was worth sharing.
2. To post MadCap’s reply to her support case which essentially had the same steps as our solution – hence we got our DIY solution sanctioned by MadCap.
3. And to point out that our solution can also help us address our own problem – hence we basically couldn’t see the forest for the trees, and needed a fresh pair of eyes to consider our issue. 🙂

So it turned out that both my posts to the forum paid off. – But a small detail nagged me: M.’s greeting on the forum sounded like we knew each other, but her user name didn’t ring a bell.

Conferences

Flashback to October 2010, when I attended TCUK, the annual conference of the UK tech comm association ISTC. It was only my second tech comm conference, and the first one where I presented. My talk “Getting ahead as a lone writer” summarized my experiences and lessons learned when I had an opportunity – rather than the explicit task – to raise the quality and profile of the documentation. (You can also read about the talk in my earlier posts.)

I was really nervous the night before my talk and was very lucky to find a fellow tech writer and scheduled speaker to confide in. Karen Mardahl lent great moral and practical support. This chance encounter is another succes story: Karen has since become a good friend of mine – and most recently even a colleague!

My talk went well, and from comments I could tell that some tech comm’ers in the audience got something out of it, whether it was an ideas to try and implement or a more general sense that it might be possible and worthwhile to get ahead as a lone writer.

The feedback has been very helpful by reminding me that even minor points are helpful to some. And conversely, my biggest lesson may fall flat if no one has that same problem – or I don’t present it in a recognizable way… 🙂 Since then, I try to let conference speakers know when something struck a chord, whether it’s some practical advice or an alternative perspective on things.

Mailing lists and groups

As a member of ISTC, I get a daily digest of the association’s mailing list. I must admit I haven’t gotten a lot of use out of it so far. Maybe it’s because much content is specific to the UK, such as meetings of area groups. But Friday’s digest had an entry that merits its mention here: M. had posted, using the same user name as on the Flare forum and her full name.

Now I knew who it was: One of the attendees of my talk at TCUK 2010! We had been connected on LinkedIn for a while, so I sent her a message to thank her for her advice.

It’s the people, not the tools

I sometimes think that the tech comm blogging scene may be slowing down. At other times, I wonder if I really need yet another mailing list. But as last week’s experience has taught me, different channels have different uses to connect me to other tech comm’ers. So ultimately, it’s not about this channel or that app – it’s about connecting with people. And I, for one, am glad, proud and humbled to be part of such a vital professional scene which is stronger than any one channel.

How our addiction to meaning benefits tech comm

Join me for my presentation “Addicted to Meaning: How Good Technical Communication is Like Bad Magic Tricks” at tekom/tcworld in Wiesbaden on Tue 23 Oct at 1:45 pm.

In the session, I will explore how “meaning” works in technical communication, why it sometimes fails and how you can improve its chance for success. Being meaningful in your work is harder to measure than being correct, concise or consistent. However, it is just as essential: Understanding how and why communication is meaningful to your readers can help you to make your documentation more effective and to distinguish good from bad.

Using examples from topic-based authoring and minimalism, I will illustrate the underlying working of semiotics and mental models to show:

• Why minimalism works, but FAQ’s don’t
• Why asking a friend is effective, even when he doesn’t know the answer
• How readers create meaning from documentation
• … and how good documentation is like bad magic tricks 🙂

I will put our familiar tech comm tool box into a new context, so you can get a deeper understanding and a fresh perspective on tech comm and how it fits into the bigger picture of meaningful communication.

I’ve set up the topic in two earlier posts which give you an idea how I’ll tackle the issue:

• But do we create documentation with meaning?
• How meaning works in technical communication

TCUK12 summary, likes & dislikes

This was my third consecutive year at TCUK, and I was surprised and glad to see how much I enjoyed it in different and new ways than before.

I mainly enjoyed seeing acquaintances and friends again who made me feel like I was part of the family. I was glad to help the conference organisers in a small way by facilitating two sessions. And it was great to hang out with the international tech comm “jet set”, whether they’re from England (hi, Alison, David, Elaine, Felicity, John, Jonathan, Robert and Sue) or from farther afield (hi, Charlotte, Diego, Janet, Karen, Leah, Maxwell, Morten and Ray).

I also felt more relaxed and less nervous, because my own session was a panel discussion which can only stand limited preparation. By contrast, my presentations in previous years were prone to overrehearsing… 🙂

The panel itself went quite well, even if Robert Hempsall had to bow out at the last minute. Karen Mardahl, Ray Gallon and I discussed how internationalization, specifically different language skills, different cultures and different technology affect accessibility. Thanks to our audience who contributed their own experience, it was a lively discussion and the 40 minutes went by very fast.

Likes

• Nice size. TCUK is small enough to have a very cozy, almost intimate feeling about it, yet large enough to be dynamic and diverse.
• Professional, constructive vibe. Whether they’re newbies or experienced, many delegates get involved and contribute their experiences and opinions in the sessions during Q&A and outside, in the foyers, over lunch or at the bar. I see a lot of communal participation and engagement and very little sit-back, entertain-me consumerism.
• Diversity and quality. I’ve been amazed once again at the wide variety of topics and the generally high quality of the programme:
  • The 3 keynote lectures by Leah Guren, Scott Abel and Karen Mardahl were excellent: Relevant, inspiring and entertaining each one of them! Their general upbeat tone pervaded the entire conference.
  • The 6 workshops on Tuesday (as far as I’ve seen and heard) were hands-on, very practical and applicable. Participants contributed interesting, sometimes provocative perspectives which added insights and reflection to the practical exercises.
  • The 30 sessions on Wednesday and Thursday (again, as far as I’ve seen and heard) were for the most part well-presented and an interesting mix of conceptual, high-level discussions and roll-up-your-sleeves practical advice.

Dislikes

• Sessions are too short.  At 40 minutes total, they often have 30 minutes or so for the actual presentation and some time for Q&A. I prefer presentations of 45 minutes plus Q&A afterwards, which can run for 5 to 15 minutes.
• Food. Personally, I didn’t care much for the food at the hotel, but that is a matter of taste, as always. Other delegates liked it just fine.
• No time to explore. Glancing at Northumberland from the plane, I regretted making such a tight schedule that I saw nothing outside the hotel and the airport. It looks like a beautiful area well worth exploring.

In-depth session reports

For more details about some of the sessions I have attended, see my previous posts:

• TCUK12, day 1: Workshops & company
• Leah Guren’s Fish Tale at TCUK12
• Ray Gallon’s Hairball of Content at TCUK12
• Scott Abel on Structured Content at TCUK12
• David Farbey on editing at TCUK12

– If you’ve attended TCUK12, feel free to add your impressions in a comment below. If not, you can still add a comment or ask a question… 🙂

Leah Guren’s Fish Tale at TCUK12

After opening remarks by conference organizer David Farbey, Leah Guren‘s keynote relevant and entertaining keynote address presented several lessons from the animal world:  A Fish Tale: Improve your Career by Watching Fish!

1. Take a leap of faith – like salmon. It simply takes some guts and a little bit of faith that tech comm is here to stay, else you won’t be able to make a long-term plan and get behind it.
2. Stay in school for better chances of survival – once you took that leap, keep honing your skills, keep developing. There are lots of ways and many don’t require the same amount of time and money as going to a conference, whether it’s e-zines, forums, user groups or webinars (some excellent ones are actually free!) Be sure to make your professional development part of your regular work schedule.
3. Invest in better PR – the difference between a carp and coi is mainly the prize tag – which is thanks to better PR for the coi. Communicate your value that you bring to the company and to its customers. We know how much words matter, so we can do better than calling ourselves technical writers. “Information architects”, “content strategists”, even “technical comunicators” can make more money.
4. Find the right stress – (sorry, I forgot how this related to fish… 😉 ) Tackle your fears, get a new challenge and pick the kind of stress where you’re still in control, feel stimulated and can grow.
5. Active swim in a larger pond – because like a carp you will grow (professionally) in relation to the size of your “pond”. Find opportunities for growth how you can be the expert in your environment.

I’m sure I forgot a couple of Leah’s lessons. Nevertheless, I want to add an additional lesson that I’ve found important: Know the secret of the birds. That means know how your enemies tick, so they don’t eat you. Or if they’re not threatening: Seek heroes outside of your immediate field. Sure, you won’t be able to fly like a bird, but you can still find birds inspiring.

3 motivators you share with your tech comm readers

What motivates you to work most likely motivates most of your users in their jobs, too! You still need to know your audience, their tasks and background, but the good news is that you have some basic motivators in common. And these can help you understand what makes you happy at work – and what makes your users successful in their work with your documentation.

The three motivators

I take my cue from Walter Chen’s post “The science behind what motivates us to get up for work every day“. I want to focus on three motivators Chen quotes from Daniel Pink:

The 3 real reasons that motivate us to work hard every day

Pink explains … that there are in fact just 3 very simple things that drive nearly each and everyone of us to work hard:

1. Autonomy: Our desire to direct our own lives. In short: “You probably want to do something interesting, let me get out of your way!”
2. Mastery: Our urge to get better at stuff.
3. Purpose: The feeling and intention that we can make a difference in the world.

The motivators for technical communicators

Pink’s model resonated with me, and I think this is exactly what motivates me to do good tech comm work and try to get better at it:

• Autonomy for me means to find something good in the benign neglect that often meets my efforts. Of course, I have specific products, deliverables and deadlines to comply with, but our documentation team is lucky enough to be able to define its own standards and processes as long as they’re feasible.
• Mastery is the challenge to write better documentation. When I revisit obsolete documentation that I’ve written some years ago, it makes me smile: Seeing where I’m coming from and what I wouldn’t do anymore gives me a sense of progress. I’m still using task orientation and topic-based authoring – but I wouldn’t awkwardly mix concept and task in the same topic like this anymore.
• Purpose for me is my reward that my readers can be more successful or simply faster in their work if and because I’ve given them the right information at the right time.

So in a very personal, non-scientific way, I could validate these three motivators.

The motivators for documentation users

I don’t think I’m all that different from my readers in this regard. I believe they get motivated by the same things – they’re just in a different job.

So I try to keep in mind the motivators when I structure and write my documentation:

• Autonomy is tricky, of course. Someone looking up documentation has just given up the autonomy of a self-directed life and needs instruction or information. But I still try to acknowledge this and follow Pink’s advice above: “You (dear user) probably want to do something interesting (or important), let me (give you what you seek and) get out of your way!”
• Mastery is where tech comm can really excel. By presenting essential information concisely and clearly we can make it easy for our users to master their tasks and their use of our product. For this mastery, it doesn’t matter whether users learn from the documentation and internalize a skill or whether they simply know where they can look up again quickly what they don’t need to remember.
• Purpose is frequently neglected, I think. Often documentation focuses on the how, and forgets the why. But there is no sense of purpose without a why. Granted, not every topic can address the big questions of life and the universe. But as long as there is an elegant and possibly noble reason for why our product and its tasks are this particular way, it’s worth sharing it. It will give our customers an extra motivation – and make them more loyal users.

Is this what motivates you? Does it work for your readers or do they have other motivations? Please leave a comment.