The approach we advise to writing documentation is based on using the DITA norm as an information model.

DITA (Darwin information typing architecture)

DITA includes three specialized topic types: Task, Concept, and Reference. Each of these three topic types is a specialization of a generic Topic type, which contains a title element, a prolog element for metadata, and a body element. The body element contains paragraph, table, and list elements, similar to HTML. A (General) Task topic is intended for a procedure that describes how to accomplish a task. A Task topic lists a series of steps that users follow to produce an intended outcome. The steps are contained in a taskbody element, which is a specialization of the generic body element. The steps element is a specialization of an ordered list element. Concept information is more objective, containing definitions, rules, and guidelines. A Reference topic is for topics that describe command syntax, programming instructions, and other reference material, and usually contains detailed, factual material.

That’s DITA.

Let’s take DITA a step further, adding a typology to what DITA considers as topics in order to help authors categorize writing.

DITA refers to this as specialization for industrial sectors.

DITA specialization

DITA allows adding new elements and attributes through specialization of base DITA elements and attributes. Through specialization, DITA can accommodate new topic types, element types, and attributes as needed for specific industries or companies. The extensibility of DITA permits organizations to specialize DITA by defining specific information structures and still use standard tools to work with them. The ability to define company-specific information architectures enables companies to use DITA to enrich content with metadata that is meaningful to them, and to enforce company-specific rules on document structure.

That’s all fine, specialization is what we propose, but how do we transform this into a practical method.

The typology we define is to help authors know what to write, find and reuse information easily and stay pertinent.

We call elements of this typology information blocks (typed DITA topics). These are typically:

  • Introduction, and /or About
  • Usage
  • Pre-requisites
  • Example
  • Theory
  • Tips
  • Terms
  • Pitfalls

Why differentiate like this?

Writing software for documentation, in our experience has never been easy. Most editors don’t master the process easily.

This differentiation allows for sharper authoring guidelines. As a spin-off it allows more pertinent search for re-use (in tools that know how to do this).

Editors don’t always employ specialized technical writers and their developers hate writing documentation. Our approach has always been getting the two to work together.