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

David Farbey on editing at TCUK12

In his session Letters From The Editor, David Farbey talked about what editors do, what they can do and what they can do better.

What editors do

Basically, it is the job of editors to mediate relationships. They mediate the relationships between the writers, their content, their audience and their organization (such as a company or institution).

More specifically, they still do much of what Robert Van Buren and Mary Fran Buehler laid out in their seminal booklet Levels of Edit of 1980 (a PDF version is available online). Mind you, much has changed since, but many of the basic principles still apply. So David took his cue from the 9 levels of edit to propose 3 classes of edit today:

• The policy edit is for coordination and planning. It ensures that the content is appropriate to the organization and its audience, that it complies with the organization‘s policies and strategies.
• The copy edit handles all the technical issues of content, from spelling and punctuation to formatting and textual integrity. It ensures that the text is functionally correct and clear.
• The developmental edit addresses the content itself in the last and most important stage. It ensures that the language is comprehensible and presents the text’s substance appropriately and clearly, whether it is a concept or a procedure. (This is not the same as a content review! A subject-matter expert reviews whether content is correct and complete, while a developmental editor ensures that such content is presented in clear and comprehensible language.)

 All three classes of edit occur at the same stage in the content workflow:

1. Policy edit: Author and editor plan content production.
2. Author writes content.
3. Subject-matter expert reviews content.
4. Author corrects content according to review.
5. Developmental edit: Editor edits content.
6. Author corrects content according to edit.
7. Copy edit: Editor proofreads content.

Advice for editors

• Check the text and the publication, not the product or the facts that are described in the text, that’s the task of the reviewing subject-matter expert.
• Offer constructive criticism, don’t evaluate or grade the text.
• Mentor the writer, if necessary, don’t manage the writer. If you are his or her manager, put on your editing hat, not your managing hat.
• Create and apply guidelines and policies:
  • Create and comply with a corporate style guide as a searchable collective memory to guide the work of writers and editors alike.
  • Agree on who has the last word.
• When editing topics in structured authoring:
  • Edit in chunks
  • Add a step in the workflow before the copy edit: Editor or writer compiles document
• When editing in an agile environment:
  • Consider when a content item is shippable
  • Consider when the document as a whole is shippable
  • Change the workflow so steps 2. through 4. above become: Write and review in sprint.

5 steps from legacy documentation to topics

To move to topic-based authoring, you need to convert existing documentation into topics. The efforts shouldn’t be underestimated, but it’s actually a pretty straightforward process. I’m describing how to convert sections in manuals, but it’s much the same for most content, whether it’s FAQs, wiki articles, training materials, etc.

Prerequisites

• Some knowledge of topic-based authoring. You should know the topic types you will use, for example, concepts, tasks and reference topics.
• Have a tactical framework. Ensure you know the documentation structure you aim for and how you will get there in a project. Consider for example the Top 4 tactics to structure legacy documentation.
• A style guide to which your documentation complies definitely helps.

1. Identify topic type(s) per section

Define each section in your manual as one of your topic types, for example, concept, task or reference.

If topic types are mixed…

A common problem at this point is that you may have topics that mix topic types. For example, your topic contains concept information and task information. Or task information and reference information. For details, see When topics don’t quite work.

2. Re-chunk sections to make them topics

Redistribute your content so each section becomes a topic:

1. Cut out everything in a section that doesn’t fit the selected topic type and put it aside.
2. Ensure that the topic that remains:
• Is either a concept or a task or a reference.
• Presents only one idea.
• Has only one purpose.
• Can stand alone, in context with others.
3. Take the content you have cut out and put aside and do one of the following:
• Integrate it into an existing topic where it fits better.
• Create a new topic for it.
• If it’s not relevant, throw it away. 🙂

If topics are too complex…

A common problem at this point is that you can end up with one or several topics that are too complex. Then you can try the following:

• If you can describe a topic’s content as two separate, but related ideas, turn it into two sibling topics.
• If you can fully summarise a topic’s content only as a very complex idea, turn it into a parent topic and create children topics for it.
• If it’s a long procedure with more than 10 main steps in a top-level numbered list, try to cut it into two topics approximately in the middle.

3. Re-sequence your topics

Re-arrange the sequence of your topics, so they flow nicely when users read not just one or two of them, but need to learn a complete setup or operational process.

1. Verify that your topics are in the best possible sequence and re-arrange them if necessary. You might want to try these categories:
• Setup, in the sequence of tasks.
• Operations, in the sequence of tasks.
• Reference topics, in alphabetical order.
• Concept topics can either appear as a section of their own, ordered from the large/general to the small/particular, or among the other topics as appropriate.
2. Verify that your topics are complete and add topics, if necessary:
• Do you have concept topics for all major elements in your task topics which explain what these elements are?
• Do you have task topics for all concept topics which explain how to set up and operate the elements

If the topic sequence doesn’t flow nicely…

A common problem is that the topics don’t flow as nicely once you have chunked them into stand-alone pieces. In this case, add some “glue” topics which orient readers and ensure a good flow, for example, at the beginning of chapters in books. Consider including these glue topics only in print deliverables; maybe they are not necessary in your online help.

4. Rewrite headings to guide readers

Often your legacy section headings work in the context of your manual, but don’t give users enough orientation when they read just one or two topics. Rephrase them so users can quickly dip in and out of your documentation. Keep these guidelines in mind:

• Reflect the user’s need or goal in the heading.
• Phrase headings so users know what’s in the topic when they see only the heading in a link in another topic.
• Try to make headings unique so there’s no confusion when they appear in search result lists.

5. Add links between related topics

Ensure that your topics have links or cross-references between all related topics:

• Do your concept topics link to corresponding task topics – and vice versa?
• Do your task topics include or link to prerequisites and next steps?
• Do your task topics link to corresponding reference topics?

Your turn

Do you find these steps helpful? Have you converted documentation into topics before? Please leave a comment.

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.

 

Are serifs or non-serifs easier to read?

Are serif fonts easier to read than non-serif ones? No, is the conclusion in Alex Poole’s exhaustive post.

After reviewing more than 50 studies, Alex comes to the conclusion that “serifs or the lack of them have an effect on legibility, but it is very likely that they are so peripheral to the reading process that this effect is not even worth measuring”.

Serif vs. non-serif fonts as illustrated by Wikipedia

Thanks to Chris Atherton for pointing me to this post which perfectly complements one of my most popular posts: Ragged-right or justified alignment?

I must admit this came as a surprise to me, since I always liked the argument “Serifs are used to guide the horizontal ‘flow’ of the eyes”. But unfortunately, simply liking an argument doesn’t make it so. 🙂 It might just be a case of confirmation bias, as in this case…

Typography primer

Today’s bonus link is to a cool, comprehensive article in Smashing Magazine about typography including justified text, hyphens, dashes, smart and dumb quotes: Mind Your En And Em Dashes – Typographic Etiquette.

When topics don’t quite work

If a topic in your documentation gives you trouble, seems homeless or doesn’t quite “work”, it’s probably because it is mixing topic types.

The company I work for has started to roll out topic-based authoring over a year ago. We’ve seen several benefits already: Topics are easier to find and follow for users and more efficient to maintain for writers. But the transition has not been without problems…

The curse of the ornery topic

One of the biggest headaches for us is the “ornery topic”. Here’s how you can tell an ornery topic:

• It seems homeless. Regardless where you put it, it seems out of place somehow.
• It doesn’t quite work. It doesn’t really do what the heading says, but somehow does more or less or differently.
• It seems essential. You really need the information. You can’t just cut it out.

The #1 cause for ornery topics is mixing topic types. What often happens is this:

1. We need to explain how to do something, so we write a procedure.
2. Then we need to provide some context about the task, so we include some concept information.
3. Then we need to tell the customer about all the available settings and options, so we include some reference information.

Voilà, our topic’s become ornery! – If you’re into project management, think of this as the molecular tech comm version of scope creep.

The cure for the ornery topic

We’ve by now found several ways you can bring an ornery topic back in line:

• Extract concept information, put it into a concept topic and link to it.
• Omit reference information in the topic, if it is sufficiently explained elsewhere, for example in online help entries.
• Make the procedure rule the topic structure, so you have intro/context, prerequisites, procedural steps, result.
• Limit context information to what fits into an introductory paragraph (and link to other concept topics)
• Limit reference information to what fits into individual steps (and link to other related reference topics)

Your turn

Have you met any ornery topics in your documentation? How have you addressed them? Feel free to leave a comment…

Recommended read: Practice technical writing

Becoming a better tech writer requires practice.

Mike Pope, tech editor at Microsoft in Seattle, has a brilliant blog post about 12 ways to practice tech writing. The catch is he means “practice” like a musician, so you learn to do stuff better than yesterday – instead of just doing the same things over and over.

Over the last years, I’ve tried all 12 ways, and they’ve all helped me to become a better writer. And most of them can be fun, too, at least most of the time… 🙂

Here are just six of the ways as a teaser, but I highly recommend you head on over to Mike’s post to find out about all of them with details and examples.

1. Read other technical writing attentively.
2. Read about writing.
5. Writing something outside your usual material.
7. Edit someone else’s work.
10. Learn new tools and new ways to use your existing tools.
11. Talk to other writers.

How a degree helps a technical writer

A college degree can help you in technical writing, though maybe not in the ways you expect.

How relevant is a college education for the field of technical communication? A couple of very good and influential tech writing blogs have recently discussed this issue:

• Why Tech Comm Is a Career Path of Last Resort for Students, by Tom Johnson, about an English department
• Rhetorical theory vs. tech comm reality, by Ryan Fulcher, Scriptorium, about a tech comm program

The question is both pertinent and impertinent, because Tom and Ryan frame it in a way that devalues college education [… at least in the specific program they are criticizing, see Ryan’s comment below. 18 Nov 2010]. Tom says tech comm “should not be taught in the context of an English department, because [it] is not understood or encouraged in traditional English curricula.” Ryan says he’s gained more useful knowledge in 5 months in the job than in his entire time in the tech comm MS program. I cannot argue with their experiences, and I cannot hope to convince them otherwise.

To help anyone with similar questions who’s in college now or has recently graduated, I can offer my own alternative assessment: How a college degree helped me become a passionate and, I dare say, good technical writer.

What I sought

Computer Science and Business as a combined major was how I started college. I sought to learn how to build software and how to run a business. What I got was learning by rote, too much how it’s done and not enough why and how it could be done better. I dropped the major after a semester.

I had embarked on rational and reasonable education and found that my heart wasn’t in it. I just couldn’t see myself spending several years getting a degree as a means to an end. I expected college to teach me something that was interesting in its own right, not a promise that I could apply it in a future job, or maybe not.

American Studies is what I declared as my major after two weeks of soul searching. That’s where I found my academic home. The curriculum was heavy on literature, social history and culture. The emphasis was on understanding what holds the USA and its culture together, to come to terms with its cultural and artistic developments, and to use whatever academic theories could be made useful.

Over ten years ago, I’ve received my M.A. in American Studies. I’m a technical writer by choice and practice, with the heart and the outlook of an Americanist.

What I learned

In American Studies, I learned a lot of things. Almost all of them do not directly relate to technical writing. Here are some things that I’ve found useful and applicable as a technical writer:

• How to write long, coherently argued, understandable papers in correct English. It took me a long time to get it right. It took me longer yet to realize the importance of tailoring my message and language to my audience. And it took me even longer to realize that all this combined is a rare and marketable skill.
• How to explain something that defies explanation to people who think they already know how it works. After you’ve ever tried to explain America to Germans who have it all figured out from movies and news media, writing user manuals is actually pretty easy. Most products I’ve dealt with are less complex than a country of 310 million people, even if you only regard the most recent 400 years.
• How to cope with complexity. Literary studies can appear pretty neat, especially when you deal with only one author or one book. Studying a country and its culture is a more daunting task, not least because the people carry on so, with no regard for your studies. Trying to keep your insights reconciled with an ever-changing reality is a good preparation for your survival in large corporate environments and their organisational quirks.
• How to organize to finish. Formulating a thesis and then framing and arguing it was part of my later assignments. That was a good preparation for writing user manuals from scratch. The “thesis” in that case is the easy part. The customer wants to do stuff with the product and look cool while doing it. But the rest is again up to the writer: Framing the text in a context of use, consulting all available sources, explaining it in the most understandable and most efficient way.
• A turn of phrase occasionally: That a question can be both pertinent and impertinent (see above) is something that I learned from Thoreau’s Walden, the second paragraph of the “Economy” chapter to be precise.

What I know now

A college education can work very well for you, if you take it for what it is and don’t expect something that it isn’t. Stanley Fish makes a very astute argument for what a university can be and do:

When it comes to justifying the humanities, the wrong questions are what benefits do you provide for society (I’m not denying there are some) and are you cost-effective. The right question is how do … your program of research and teaching fit into what we are supposed to be doing as a university.

It’s important to realize that this kind of education comes with no guarantee: It guarantees you neither a job, nor happiness, nor that you’ll always be right or make the right decisions.

But it gives you the tools to gather information, take responsibility and make the decisions that affect your life. In short, such an education can give you hope. In the words of Václav Havel, writer, dramatist, and the first President of the Czech Republic:

Hope … is not the conviction that something will turn out well, but the certainty that something makes sense, regardless of how it turns out.

Your turn

What did you get out of a college education? Was it useful for immediately applicable skills? Was it instrumental to become who you are? Or was it a waste of time?

What’s in a (serial) comma?

An example of a missing serial comma got tweeted my way which was too good to be true:

Among those interviewed were his two ex-wives, Kris Kristofferson and Robert Duvall.

And here’s the guy who was married to both, Kris and Robert… 🙂

How and why to estimate writing efforts

Estimating your writing efforts and deadlines is difficult, but essential.

Can you reliably estimate the time you need to write documentation? And the date when you can deliver? It often seems a daunting task because it depends on many external factors:

• The quality of specifications and designs.
• The availability of the finished product.
• The accessibility of subject-matter experts.
• The punctuality and diligence of reviewers.

It also seems futile to spend time estimating efforts when you know you don’t have enough time anyway. But even though it’s difficult and takes time, I recommend that you do it.

Why estimate?

If you don’t do it, someone else will make assumptions about your schedule. Even if you’re just left with the ever decreasing time between delayed development and scheduled shipment.

Estimating makes documentation accountable, in both senses of the word:

• You can explain the time you will spend on documentation. So it allows you to plan and budget the time. Share the estimates with your manager, and you can also share responsibility for the efforts.
• You can also be held accountable for the time you have spent. With estimates, you only will have to justify the specific difference that you ran over the plan. That’s much better than arguing about the complete time which may “seem kind of long” to your manager, though you know “that’s just how long documentation takes”…

Estimating makes documentation more transparent, in other words. It gives you and other stakeholders specific numbers to talk about ahead of time. It gives everybody more control over the documentation process.

For example, I once faced the complaint from product managers that documentation held everything up, that we could ship sooner, if only the tech writer got his act together. By introducing estimates and refining the reporting, I was able to show that it was specifically the reviewers which held up the process. Everybody took the estimated time, more or less, but reviewers delayed their tasks unduly. In fact, one late reviewer was a product manager who had voiced the complaint…

What to estimate?

You get what you measure and estimate. Or in the words of Tom DeMarco: “You can’t control what you can’t measure.”

If you estimate number of pages per day, you’ll get reams of paper. But that doesn’t guarantee that the documentation is useful and/or accurate.

If you count the number of features, options and buttons and base your estimate on that, you’ll get a thorough description of the user interface. And a customer who says, “Don’t tell me how it works, tell me how to use it.”

Apply task-oriented writing and estimate topics, instead:

1. Look at the specifications and designs to understand what’s being developed or produced from a user’s point of view.
2. Distill or translate what you find:
   • Identify modular concepts that users will need to know. A microwave convection combination oven can use descriptions of both concepts with their principles and different use cases.
   • Sketch out user workflows to set up and operate the product and break them down into individual procedures. That oven’s manual will probably have procedures to set it up, to thaw frozen food, to heat food (using the microwave), to bake stuff (using the convection), and to clean it.

A high-level view of the topics and their complexity allows you to make a rough estimate how long you’ll need to create useful topic-based documentation.

How to estimate?

Estimate efficiently. I once estimated a one-month project so well, I was off by two hours in the end. The problem was that it took me two days to crunch all the numbers… I can’t recommend that.

So don’t try to be 100% accurate in your estimate, if it takes you a long time to do it. Here are a few ideas to spend less time on estimates:

• Look at past efforts: Most likely, you’ll do some reporting anyway. Use this as the basis for future estimates. Maybe you’ll find an average time you take to write a concept topic. And one time period for easy and short procedures and another for more complex ones.
• Refine your estimates and average sizes over time: No need to get it perfectly right the first time, especially, if you start estimations on your own account. Try to run the numbers beneath the radar before you come forth with them.
• Trust the law of averages: What extra time you need for one topic, you’ll probably save on another.
• Trust your experience: After a while, you won’t need to sketch out individual topics. You’ll be able to take an adequate measure from looking through the spec or design.

Further reading

To learn more, check out:

• Donald LeVie’s Intercom article “Documentation Metrics”, available via EServer
• Steven Jong’s STC paper “Measuring Quality”, available as PDF
• Gretchen Hargis, et al., “Task-Oriented Writing for Techies“
• Wikipedia on software metrics which has the Tom DeMarco quote

Your turn

Do you estimate your efforts ahead of time? Is it worth the extra effort? How do you use the numbers to your advantage? Please leave a comment.