Topic-based Information Development
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
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
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.
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
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.
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.
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
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!