Ghada Captan, Thomson Financial

Preceding issues featured articles on writers’ struggles in adopting topic-based writing:
Helping the Strugglers: Thoughts about making the Leap from Linear Books to Linked Topics and Making the Leap to Topic-based Writing. This article looks at the nature of this struggle.

When encountering topic-based writing for the first time, we may experience a range of emotions including

  • Excitement—“Wow, this is great. I can stop worrying about how to present information and focus instead on what really matters—helping the user.”
  • Openness– “It’s different from what I do now, but I can see how it might be good.”
  • Skepticism— “Why should I change what I do now?”
  • Fear (and as a result, resistance)— “This is taking away my control over what I write and robbing me of my creativity.”

Writers who experience exhilaration or openness do not struggle with topic-based writing. So let’s focus on those who experience skepticism or fear. Specifically, let’s consider what underlies these emotions.

What motivates us as writers?

Technical writing requires a range of skills and draws people from a wide range of backgrounds, and with a wide range of strengths. At one end of the spectrum, we may be highly analytical professionals, perhaps with a strong programming or engineering background. As such, we derive satisfaction from structure and from actively looking for and establishing patterns. On the other end of the spectrum, we may be highly creative individuals who come to this profession because of our passion for the written word. We derive satisfaction from novelty and prize a clever literary device and a well-turned phrase. Of course, none of us is at one extreme or the other; we integrate both the right and left sides of our brain in the service of our readers.

Regardless of our writing orientation, we all share one goal: to learn the products or services we document, inside and out, so we can provide the information our users seek. We usually operate with limited time and resources. Under this pressure, we sometimes confuse our need for information about our products with our users’ need for a solution.

What do our users want?

Let’s face it: users don’t turn to Help for recreational pleasure; they come to Help—usually as a last resort—to solve problems. Finding a solution for an immediate problem is what gives our users satisfaction. Like us, our users operate under time and resource limits. In addition, they may have a lot riding on finding the right information. In such circumstances, we owe our users a direct answer to their questions.

This is where topic-based writing enters the picture. A direct answer addresses only a single question. If a user doesn’t see an answer to her question in the first few words, then she is likely to feel frustrated and look for another topic. If we answer three questions in a single-topic, it serves only those users whose question we answered first. We lose the opportunity to help users with answers to a second and third question.

Over time, as technical writers we recognized that users generally come to Help seeking:

  • Instructions on how to perform a specific task.
  • Understanding of underlying concepts to inform their decisions.
  • Details about a specific component.

It is no accident that the DITA topic types are: Task, Concept, and Reference.

Helping our users

Given the direct correlation between writing discrete topics and our ability to help our users, why would any of us struggle with a topic-based approach? For many of us, topic-based writing may seem:

    • Counterintuitive. We want to present the whole picture, but each topic paints only a part of that picture.


      : If we remember that our users often need only one answer, then we can be more accepting of topic-based constructions. For those users seeking a big picture, we can link topics and provide overviews.

    • Restrictive. We want to invent rather than follow a defined structure.


    : On first approach, we might feel that following a pre-defined model constrains our creativity and diminishes our sense of ownership. But as we learn and master the model, we begin to experience the thrill of creating within a structure and the unique contribution we each add to enrich the model.

Consider, for example, how many well-constructed topics we as a community have created, and continue to create, using a structured approach like DITA. We may reuse these topics, of course, but essentially, no two discrete topics are the same.

Making a comfortable transition

Transitioning from narrative to topic-based writing often entails multiple layers: a new mindset, new tools, a new workflow. To ease the transition, we should aim to:

  • Set a realistic pace. Introduce change in only one area at a time and allow adequate time for writers to get comfortable with one change before introducing the next.
  • Encourage flow of information. Provide an ongoing forum for training, mentoring, and editorial exchange.
  • Invite innovation. Encourage pioneers to test the waters and share their success with more cautious colleagues.
  • Engage the entire team. Get buy-in from all team members, particularly for strategies and procedures generated by a special committee.

With the right perspective, we can transform skepticism and fear into openness and excitement.

Share your ideas!

If you have a topic you think would make a good article for a future issue of the e-newsletter please send it to Articles are typically between 500 – 1000 words in length. We look forward to having our e-newsletter readers weigh-in!