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.


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. 🙂

Getting mileage from a tech comm mission statement

If you have a mission statement for technical communications, you can use it to anchor several strategic and tactical decisions. I’ve suggested a few general reasons Why you need a tech comm mission statement in my previous post. The valuable discussion that ensued led me to think we can get some mileage from a mission statement in some high-level tasks further downstream.

Consider a mission statement that says: “Our product help provides users with relevant product information at the right time in the right format.”

Defining audiences and deliverables

You can keep your audience in focus with a mission statement. Do you write for end users? Maybe there are different types, such as professionals vs. amateur hobbyists? Do you also address colleagues who expect to find internal information in the documentation? The mission statement above doesn’t specify it – and hence can be expected to address everyone who uses the product.

You can also derive your deliverables from a mission statement. Do you publish to several formats or only to one? What is your priority of formats? Web help first, PDF second seems a standing favorite that’s recently been disrupted by the emergence of mobile output. The mission statement above merely mentions the right format – so you need to figure out what format is right for your audience types. You can use personas to determine how your users work with the product – or better yet: Observe or survey them!

Defining information model and processes

You can derive your information model, the structural standard of your documentation, from your mission statement. This model should help you to reach the goal described in your mission and serve your audience. For example, topic-based architectures have long been popular. If you need to retrieve small chunks of information, for example to share steps in a task or exception handling advice, consider a more granular standard such as DITA.

Your processes should outline a repeatable, efficient and effective way to create your deliverables so they address your audience and, once again, help you to achieve your mission goal.

Your information model can suggest which topics or elements to create need to be created and updated for a given product or enhancement. Together with your processes, this makes it easier to plan and estimate documentation efforts – in theory at least…

– But with some management support and some persistence, a mission statement and some strategic decisions piggy-backed on to it can help you get out of the proverbial hamster wheel.

What do you think? Can this be helpful? Or is it too far removed from real life? Do you have any experience with a larger documentation strategy based on a mission statement? If so, did it work?

EPPO redux or: Mark Baker is on to something

“For users, Every Page is Page One,” says Mark Baker. Users can land anywhere in your documentation and start consuming away. That’s why structured authoring is more than one method among many – it’s an imperative to create meaningful content and to stay relevant as a technical communicator.

Few technical communicators have recently chipped away at unquestioned conventional wisdom as profoundly as Mark Baker in his blog Every Page is Page One (EPPO). Here’s his thesis in a nutshell – EPPO redux, if you will.

The following is my boiled-down edit of the session description of Mark’s workshop at the Intelligent Content Conference yesterday. I can only claim credit for the mistakes and misunderstandings I introduced, but everything below is essentially Mark’s wisdom. I share it because I find it sensible and highly relevant – if you do, too, I encourage you to follow Mark on twitter and on his blog.

Writing Every Page is Page One Topics
Mark Baker, President, Analecta Communications Inc.

For users, Every Page is Page One. So write good Every Page is Page One topics, even when you have a large amount of related subject matter to cover. Construct information so readers can meet their information needs, no matter where they land. When covering a broad array of subject matter, don’t design the information to be consumed sequentially or hierarchically like a book.

Successful Every Page is Page One topics

  • Define a limited purpose: Do one thing per topic, do it well and completely.
  • Stay on one level: Be broad or be specific in a topic, but pick one and stick to it.
  • Establish context: Orient readers so they know where they are.
  • Conform to type: Orient readers so they know what type of topic they see, help the writer be consistent and complete.
  • Assume the reader is qualified: To help readers get qualified offer links in a topic, not details.
  • Link richly: Encourage the reader to explore, anchor the topic in its context.
  • Provide the big picture: Create explicit high-level picture, don’t bury the big picture in the htopic sequence or hierarchy.

Lessons from Ray Gallon on cognitive UA design

Context is everything: Support your users in their integrated competency learning and embed user assistance in the user interface and conceptual context in task topics. That’s in a nutshell what I took away from Ray Gallon‘s  webinar “User Become Learners”, the first in a series of 3 webinars on “Cognitive Design for User Assistance“.

To catch up before the second webinar on Tuesday, 29 January, read on or watch the recording made available by Adobe who hosted and sponsored the webinar (requires an Adobe ID) or check out Ray’s slides.

Evolving learning needs

What we need to learn changes all the time – it even seems to change faster these days. So for us technical communicators, says Ray, it’s not sufficient to show users how to use or learn a product. Beyond that, we need to teach users how to learn to adapt a product to their evolving needs.

To back up his claim that learning needs are not static, Ray showed OECD statistics for the last 50 years: In average European working days, routine manual tasks are down. Routine cognitive tasks way down. Non-routine manual tasks are way, way down. By contrast, expert thinking is way up. And complex communication is way, way up!

To help users meet these challenges, technical communicators need to offer decision support and to convey knowledge. Users need to be able to decide which problem they need to solve and if and how they can go about it. This requires knowledge: They need to understand contexts, underlying concepts and applicable tools. All this means much more than just explaining a product’s user interface – which would be routine manual and cognitive tasks that are on the way out.

How minimalism can help

Ray recalled the core principles of decision support, according to the U.S. National Research Council. Half of them relate directly to the tech comm principles of minimalism (as summarized by JoAnn Hackos on her blog recently):

  1. Begin with the users’ needs in decision support; focus on users’ actions in minimalism
  2. Connect information between producers and users in decision support; understand the users’ world in minimalism
  3. Design for learning in decision support; ensure that documentation is findable and contains troubleshooting information in minimalism

Just because minimalism emphasizes hands-on practice doesn’t mean it shuns conceptual information, says Ray. So to add value to the documentation, describe applicable tasks, not just the user interface.

That means we tech comm’ers don’t just merely describe the menus and icons. Instead, we must also get involved in the design of the product, especially the interface with its labels and error messages and pop-up hints.

This way, usage of our documentation can improve drastically: Rather than supporting rote memorization or, worse yet, require users to look up the documentation repeatedly, users can learn from the documentation and apply what they find to decide what they need to do and how.

To carve up or synthesize?

One of the most important consequences of Ray’s paradigm for us tech comm’ers is that it effectively abolishes a dear dogma of topic-based authoring, namely the separation of concepts and tasks. Ray explains that just because we need to understand these areas separately (when we make sense of products during analysis) doesn’t mean we need to keep them separate when we present them again to users (during synthesis). Imagine a pizza: You need to understand crust, tomato sauce and toppings separately – but you would never serve them separately to the user. (For more about this, see Mark Baker’s blog post.)

For documentation, this means to empower the user: Read/understand once, apply many. I think the parallel to single sourcing is obvious and deliberate: Write once, use/publish many. Give users all the information they need – and only that, no more, nada mas! (And offer it in a way it’s findable immediately.)

Specifically, put conceptual information where it is most useful, into tasks. Integrating conceptual information into tasks avoids that concepts remain abstract and removed. In addition, progressive disclosure can help with the efficient embedding of user assistance into the user interface.

My lessons learned

I think Ray’s approach makes a lot of sense. It can improve many a help system that follows the letter, but not yet the spirit of topic-based authoring.

But two factors in my daily work dampen the effect of Ray’s ideas for me:

  • We use a DITA-based information model which allows and in fact encourages contextual information as part of task topics. We want to ensure that users understand when they need to perform a task and why. I believe the <context> and also the <prereq> element in DITA serve this purpose well, without fully replacing concept topics.
  • Ray’s assertion that “good user assistance is only needed once” is a bit too idealistic for many software products I have documented. Many are very complex, some are poorly designed to boot to allow the user to safely deduce a general principle about the product. So Ray’s paradigm does require not merely the technical communicator’s participation in the design phase, but actually good design. As Ray said during the Q&A session, “This is easy to explain, but hard to do.”

Address information overload in tech comm

Addressing information overload helps your user assistance succeed when knowing your audience and offering correct and concise content is not enough. You can have great topics well-written and well-structured, if they’re part of an information deluge, they won’t help your users get their stuff done.

I take my cue from a post by Nathaniel Davis over at UX matters called “IA Strategy: Addressing the Signatures of Information Overload“. Nathaniel describes six such signatures. I think at least three of them have something to say why and how too much information fails in documentation, too.

1. Feedback

Feedback is the essential reality check to determine whether users suffer from information overload. Customers may report that they’re not sure they’ve found the right information or they cannot apply it efficiently. Even if the content is fine topic by topic, the bulk of information is unmanageable. In this case, consider improving search and browsability for more efficient use of the documentation.

2. The utility gap

The utility gap means that customers only use a small fraction of all the information they have at their disposal. As Nathaniel says, it’s what I have vs. what I use.

If certain user types experience utility gaps, consider addressing them with special documents. For example, you could assist novice users with a quick start document. Or address a special use case which only requires one of the many processes, plus some reference information. With topic-based authoring, it’s usually easy to create such additional documents by re-using the relevant topics. (Maybe add one or two specific “glue topics” to make sure the new document still flows nicely…)

If all users experience utility gaps, consider progressive disclosure by layering your content. The benefit of offering all content within three mouse-clicks wears off if it’s too much. Progressive disclosure structures content by providing the most essential, most frequently used topics first and more obscure information later. Make sure, however, that all topics remain searchable and findable!

3. Filter failure

Filter failure means that users lack ways to judge which information to trust and use. It’s what I can use vs. what I should use. Filter failure can be solved with tools and with content.

Customers who are confident to use their own judgment require tools to filter information. In documentation, faceted search allows users to reduce search results by categories to weed out inapplicable information.

Customers who prefer to rely on expert judgement will benefit from recommendations in the content itself. Consider adding such recommendations for certain user roles or use cases to guide customers to the most suitable information.

– Have you had symptoms of information overload in documentation? Would these strategies help users to cope? What other solutions are there? Feel free to leave a comment.

ROI of topic-based authoring and single sourcing

Breaking down content silos brings benefits and ROI to topic-based authoring, even if you have little or no translation. I’ve cut down time to write and maintain three deliverables by 30-40% by reusing topics.

Content silos

The company I work for supplies documentation for its software solution in different formats, among them:

  • Release notes inform customers about new features and enhancements in new versions.
  • User manuals describe individual modules of the product, how to set them up, how to operate them and what kind of results to expect from them.
  • Online help focuses on reference information for windows and fields, but has some overlaps with information in user manuals.

Content silos maintain separate contents per deliverable.Originally, these three deliverables were created and maintained in separate “content silos”, using separate tools and separate source repositories. So the documentation process looked like this:

  1. Write release notes in Word.
  2. Update or write user manuals in Word.
  3. Update the online help in a custom-built help tool that uses Word as an editor and Microsoft’s HTML Help Workshop to publish to Microsoft Compiled HTML Help (.CHM).

I’ve found that I could save some time by writing the release notes with the other deliverables in mind, so I could copy and paste content and reuse it elsewhere. For example, my release notes describe a new batch job which helps to automate a tedious workflow. If I describe the batch job in detail, the same content fits easily into the user manual. (Yes, it bloats the release notes, but at least the information is available at the release date, while we didn’t always manage to update the user manual in time.)

Copying and pasting worked even better once I structured the content in each of the three silos as topics. For example, a task topic from the release notes would fit almost gracefully among similar task topics in en existing manual.

But such manual copy-and-paste reuse is really not efficient or maintainable, because my stuff is still all over the place. I may write in – or copy to – four places, but then remember to update only two of them; enter inconsistency and its twin brother unreliability.

Getting real about reuse

To get the full benefits and ROI of topic-based authoring, we’ve found it’s not enough to simply write topics and keep your concepts separate from your tasks. We’ve had to adjust our documentation architecture, our tools and our process.

The guiding principle is: “Write once, publish many”. This tech comm mantra proved to be the key. We now aim to have each piece of information in only one topic. That unique topic is the place we update when the information changes. And that’s the topic we link to whenever a context requires that information.

Single sourcing is the best way to get a collection of unique topics into user manuals and online help. So we needed to consolidate our separate content silos into a single repository from which we can publish all our deliverables.

MadCap Flare is the tool we chose. It gives us a reliable, yet flexible way to maintain a common repository of topics. For each deliverable, such as release notes and user manuals in PDF and online web help, we simply create a new table of contents (TOC) which collects all topics that go into the deliverable.

With topic reuse, we define tables of contents to assemble topics per deliverable.

The writing process has changed considerably: Previously, I would focus on writing a release note entry or a chapter in a user manual. Now I find myself focusing on a specific task or concept and how to describe it as stand-alone content so it works for the user, whether it appears in a user manual or in the release notes.

The flexibilities of MadCap Flare’s conditions feature and of our DITA-based information model help us to accommodate the differences of our deliverables. We still write a few topics explicitly for a specific deliverable. For example, in release notes, short “glue” topics serve to introduce new concept topics and task topics to establish some context for the user and explain why a new feature is “cool”. In user manuals, an introductory chapter with a few topics explains what to find where and which sections to read for a quick start.

But most of the topics can now be used in release notes, user manuals and online help alike. Since I’ve gone from copy-and-paste in three content silos to single sourcing topics in Flare, the time to write and update documentation for my module has decreased by 30-40%. It’s on the lower end if a new version brings a lot of brand-new features. It’s higher if there are more enhancements of existing functionality.