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.


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.


6 Responses

  1. To issues 1 and 2: I find it especially challenging to write a good topic heading and/or purpose statement when the topic is going to be reused. The answer to “Why is this important?” from one context to the other. As a result, I think that some writers are inclined to throw up their hands and not even try.

    Most structured-authoring frameworks, like DITA, allow filtering. So I’ll often write two different purpose statements and filter them – by audience, for example (end user / operator), or by document type (quick reference / operator’s manual).

    • Thanks for your comment, Larry!

      Fortunately, most of my own topics are specific enough that their purpose stays approximately the same, regardless of their reuse context. But in other cases, we’re lucky that Flare allows us filtering to include the appropriate purpose as you describe it.

      In any case, I don’t think tech comm’ers should be discouraged to write complete topics lest they might be less than perfect in a potential future reuse scenario.

  2. […] 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 stru…  […]

  3. I was reminded of the importance of topic headings when I was looking something up on a software knowledge centre recently. I ended up expanding the TOC to about half my screen width to get any value from the TOC entries. At 5 layers deep, I had no idea which was the relevant one of the 6 consecutive topics beginning “Working with the…” (list 6 different features).
    Personally, I mostly visit knowledge centres when I have a task I need to accomplish and am stuck. I seldom have the leisure to browse them for background concept information.

    • Thanks, Sarah, for your comment!

      Yours is the perfect example and reason why we’ve gone off of weak/generic words at the beginning of topic headings: We try to omit “Working with the…” and “How to…” and “About…” as much as we can. Not only do they require too much screen real estate before you know what’s what, they also tend to hide valuable alphabetically sorted search results in the weirdest places. And I would claim that 5 TOC layers can be a sign of trouble in their own right.

      You probably don’t use our software (its an asset management system for banks and the like), but it sounds like our separation of concepts on the one hand and tasks with only essential concept info on the other hand would suit your habit of working better than the mixed topics we had before.

  4. […] Kai Weber suggests three great fixes for stubborn topics. […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: