WritersUA - Training and Information for User Assistance Professionals

Topic-based Information Development

By Tony Self, HyperWrite Pty Ltd

Bookmark and Share


Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Overview    Link to contents

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    Link to contents

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    Link to contents

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!    Link to contents

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    Link to contents

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    Link to contents

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    Link to contents

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    Link to contents

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    Link to contents

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    Link to contents

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    Link to contents

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!

Tony Self has worked as a technical communicator for almost 30 years, with the last 20 of those years specifically in the areas of online help systems, computer-based training, and electronic documents. In 1993, Tony founded HyperWrite, a hypertext and technical documentation company based in Melbourne, Australia. The majority of his work involves providing online and Internet strategy advice, innovative solutions and specialised training for customers in Australia and other parts of the world. Tony also lectures in the Technical Communication program at Swinburne University in Melbourne, and holds a Graduate Certificate in Teaching and Learning and a Graduate Diploma in Technical Communication. He is a Fellow of the Institute of Scientific and Technical Communicators (UK), a member of the OASIS DITA Technical Committee.


Copyright © 2011 WritersUA. All Rights Reserved.
shannonm *at* writersua *dot* com


The Conference for Software User Assistance

'Developing User Assistance for Mobile Apps' by Joe Welinske

UI Text Design

WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.

WritersUA Home Page First Time Here Contact Us Join Our Mailing List OASIS Member RSS Resource Directory Tools Contractors Training Articles Blogs Web Resources