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.

Saiff Solutions In The Media

- TechWhirl
- Nominated for 2015 Rice Bowl Asean Start Up

Click image to enlarge


“Barry [Saiff] truly is a force of nature – he is a consummate professional with deep technical expertise when it comes to technical writing which lets him just “get it” right out of the box. Barry pairs very strong writing skills with the ability to easily speak both “business analyst” and “software engineer” in the same meeting. Barry was the lead information developer for my product at Symantec, and I had the utmost confidence in his abilities and work ethic. On top of all that, Barry has a wonderful sense of humor and an infectious laugh that can transform the work environment in an instance. I strongly endorse Barry’s many talents and would welcome working with him again in the future.”

Angelos Kottas
Principal Product Manager, Symantec
December 17, 2010

Read more testimonials here.