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.

Advertisements

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.