Topic-based Information Development

By Tony Self

Overview

Topic-based, modular information development is a technique, rather than a technology. The change in writing technique from document-centric to topic-based can be a challenge for many technical writers. The biggest challenge when moving to topic-based paradigms such as DITA has proven to be the "major change in the document-centric mindset" required (according to a 2009 survey). The important changes in technical writing practice include the separation of content and form, using modular information units, document assembly, context-neutral writing, map and manifest files, and document assembly.

Changed Mindset

A WritePoint survey in 2009 found that the major challenge for technical writers moving to topic-based information development was the difficulty in changing mindset. Rather than thinking of manuals as single, linear documents, writers need to think of independent, re-usable information modules. To allow greater re-use opportunities, text in the modules must be designed so that the same information can be used in different combinations in different documents. This approach is referred to as "context-agnostic writing".

While it is desirable to minimise context in topics, it is absolutely vital that presentational information be totally separated from the content itself. This practice of the separation of content and form allows presentational form to be applied automatically during the publishing process, so that the same content can be formatted differently according to the document, Web site or other publication that it is used in.

Allowing topics to be assembled into different deliverable documents even though they may have different presentation formats can dramatically reduce the efficiency of document production. The main area of productivity improvement is in reducing repeated effort, such as writing or copying the same information into different publications, and then having to update the same information many times. There are also enormous savings in localisation when information is effectively re-used.

Linear vs Non-linear

Changes in reading patterns and information acquisition suggests that readers no longer want to read deeply through long, linear texts. Instead, research suggests they want to skim read, and read only the minimum to allow them to perform a task. Topic-based information structures are more appropriate for these impatient readers.

The Big Challenge: Letting Go!

Topic-based information development requires many changes in the document workflow and in the approach that technical writers take. Currently, many technical writers have control of most of the documentation process, including page layout, styling, composition, and production. Authors need to let go of the need to control all parts of the process, and follow a methodology that provides greater efficiency by moving from "crafting" documents to "producing" and "assembling".

Separation of Content and Form

Fundamental to most topic-based information development is the concept of the separation of content from presentation and delivery. The way a piece of text looks during authoring should be totally irrelevant, if that topic is going to be potentially output to different documents, in different contexts. The formatting and presentation are post-authoring considerations, and activities probably not performed by a technical author.

Minimising Context

One of the challenges of working within a modular, topic-based authoring environment is the imperative to remove context from the writing to enable re-use. The ability to re-use the same content modules is especially important for organisations managing large documentation suites, such as motor vehicle manufacturers producing documents with sizable proportions of common content.

Object Orientiation in Topic-based Information Development

The same fundamental idea behind object-oriented programming is used in topic-based information development. Rather than repeating text, or copying and pasting blocks of content from one place to another, information is structured into chunks that can be re-used multiple times in many different places. In this way, a piece of content is referenced, or transcluded, from its source location to its re-use location.

Document Assembly

Topic-based information is typically developed and managed at the library or repository level, rather than at the document or publication level. Topics are created independently of the publication in which it might be used, to increase the opportunities for the same topic to be re-used in different publications. The process of creating a published document therefore becomes a task of document assembly: choosing the constituent components and then producing that document product through an automated publishing process. The published document might be a book, a PDF, a Web site, or a Help system.

Map or Manifest Files

The topics created in a topic-based information deveopment process are usually stored in a library-level topic repository. When a publication is required, be that a Web site, a Help system, a user guide or a product brochure, the publication is specified through a topic manifest or map file. The map file simply lists the topic files that make up the publication, and specifies a hierarchy and sequence for those topics. Because formatting and styling information is not hard-coded in the topics themselves, the publishing process can apply the necessary form. For example, if a topic is used at a third level in the hierarchy of one publication, it can be automatically given a Heading 3 style when generated as a PDF. If the same topic is used at the second level of a hierarchy in a different publication, it can be generated with a Heading 2 style.

Content Management

As topic repositories grow in size over the life of a documentation project, it will become more and more difficult to find and manage information in the repository. A content management system that allows technical writers to easily search for already written content, to move and rename topics, and to reveal the relationship between documentation objects, becomes an indispensible tool.

The Benefits

Ultimately, a change of approach to writing should only be taken if there are benefits in changing. Moving from document-centric to topic-based, library-centric information development provides significant productivity and efficiency benefits. To maximise the benefits, technical writers need to invest in new skills, new tools, and a new mindset!

---