Archive for November, 2011

Topic-based authoring

November 3, 2011

Topic-based Authoring is an approach to developing end-user documentation that explicitly identifies and uses topics as a fundamental organising principle.

It is a set of practices, processes, tools, and an organising conceptual framework.

Topics are present in all human communication, but they are often implicit and not utilized as a formal organisational principle.

Contrast “writing to make the sentences and paragraphs clearer“, on one hand, with “writing to make the thinking clearer“, on the other.

The first – writing to make the sentences and paragraphs clearer – involves interaction with words and sentences, which can be explicitly identified and whose relationships can be formally described.

The second – writing to make the thinking clearer – involves interaction with topics.

When topics are implicit there are no terms to describe topics, and no vocabulary to describe their interaction and relationship. Authors can intuitively deal with and structure information without an explicit vocabulary for topics, but capturing and communicating practices and standards, and creating processes around those, is impossible.

Topics become explicit first when they are a participant in the universe of discourse of authors. This can be thought of as weakly topic-based authoring. In this stage authors know what topics are, can see them in existing documentation, and may even use them as an organising principle while planning and writing. However, there is no specialised tooling support for topics, and the topic does not have an existence beyond an organising principle in the mind of the author.

Topics become completely explicit when they become first-class citizens, with a formal existence and participation in documentation workflow from planning to implementation as an organising principle with support from tooling. This is strongly topic-based authoring. In this stage topics are both used as an organising principle, and also have a physical existence in the workflow and toolchain.

Topic-based authoring (either weak or strong) produces the traditional output media expected by users, such as books, articles and help files. However, it can also produce enhanced output such as dynamic websites.

Topic-based authoring is used by companies to aid in information planning and project management, increase automation, decrease maintenance costs, and increase reuse (including multiple output structures from the same content).