Topic-based Authoring

Topic-based Authoring

 

Did you ever notice that the documentation you received with a product is not consistent with the documentation you access online? From the perspective of the manufacturer, this is quite understandable. For each product, dozens of documents may be produced, many of them by different authors in different departments, via separate production and delivery processes. How is it possible to make all these documents consistent?

The complete answer is provided by content strategy and content management. Topic-based authoring is an essential component of a good content strategy. When topic-based authoring is employed across an enterprise, all content authors write topics. For example, instead of writing an administration guide, a team of information developers writes a large group of topics. One purpose of these topics is to be assembled into the administration guide. In addition, many of the same topics can be used in the online help, in marketing or support documentation, etc.

Topic-based authoring provides increased consistency and accuracy, as well as conserving resources through the efficient reuse of topics for multiple purposes. Instead of 3 writers composing slightly different treatments of the same subject independently, one writer creates an initial topic for a specific use. Other writers can then use the same topic for other purposes, modifying the topic if needed, through established processes that preserve all versions for future update and maintenance.

There are several key practices involved in topic-based authoring:

  1. Each topic contains a complete set of information that stands by itself, as well as links or references to other relevant topics. Because the topic may be read in a variety of contexts, the author cannot assume that the reader will see topic Y after topic X. This approach is useful even if only one type of document is ever produced using the topics, as most people do not read technical manuals cover to cover in the exact order as presented.
  2. Each topic conforms to a standard topic type. Basic types include task topics, concept topics, and reference topics. Additional types may include online help topics or process topics. Each type of topic dictates certain standards of composition that contribute to consistency, completeness, and comprehension.
  3. All topics conform to an overall set of standards that include word usage, grammar, sentence length, vocabulary, voice, and enterprise-specific or product-specific guidelines.
The cost savings produced by topic-based authoring can be significant. This is evident from answering the following question:

OK, so I’ve written my administration guide already. Now, can I just split it up into separate topics, for use in other places, without losing more than a few days of writing time?

The answer is, you can split up the document, but it’s not a simple effort to then make the resulting topics useful in other contexts. If your writers have not been using topic-based authoring practices, the sections in your guide may not stand well by themselves. Extensive rewriting may be required to render the content useful in a variety of contexts, and to improve its quality and conformance to standards. However, such an effort may be well worth the initial expense.

Even if your customers primarily use one or two documents on the same platform, what happens in a year, when most of your customers are seeking to use your content in a different way – for example, via searching Google on their smart phones? If your documents exist only as PDFs, the content within the documents is not easily searchable via Google.

You can better serve your customers in the long run, and enjoy significant overall cost savings, by investing now in the development of a comprehensive content strategy based on topic-based authoring. Saiff Solutions can help you do that.

Blog Archives

Latest Facebook Posts

Barry Saiff shared Global Coherence Initiative's photo to the group: Philippines Technical Writers. ... See MoreSee Less

Hoping you have many heart moments today… and always…

View on Facebook

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge

Testimonials

“Barry [Saiff] has extensive experience both as a manager of technical writers and as a writer. As a manager, he is fair, encourages innovation, and is open to divergent points of view. As a writer, he can grasp very complex concepts and explain those concepts to end user through administrator audiences. Additionally, he has expert knowledge of all components of the documentation process, including corporate style guides, editing, writing, working with localization, and production. Barry is very much a people person and wherever he goes, he cultivates a large network of friendly yet professional relationships. He’s worked successfully with both on-site subject matter experts as well as those across the world. During my time working with Barry, he’s run a number of successful efforts to improve the usability of documentation. In one such case, he recruited a cross-functional team to overhaul the documentation based on the recommendations of this user-facing group of subject matter experts.”

Steve Anderson
Principal Technical Writer, Symantec
December 16, 2010

Read more testimonials here.