Basic Terminology and Concepts for Technical Documentation

Basic Terminology and Concepts for Technical Documentation

Technical Writing

Within technical communication, technical writing is its largest subfield. Technical writing produces highly structured and stylistically formal technical communication—or documentation—used in many different technical and occupational fields. The format and content of this technical documentation depend on what exactly is being documented and who the target audience for said documentation is. Technical documentation is produced by technical writers.

Technical communication is used in many professional fields, such as in computer hardware and software production, in the medical industry, in consumer electronics as well as in forestry and finance. In addition to various user and installation manuals, technical writing produces, among others, technical training and presentation materials, press releases, references, and articles.

Structured Writing

Structured writing is, by nature, modular (see ‘modular documentation’). In structured documents, the actual structure and stylistic settings of the text are separated and information is organized using a meta language. Meta languages suitable for structural writing are markup languages such as those based on SGML.

Structured writing is intended to facilitate the documentation publishing process and increase the reuse of existing material in different contexts (see ‘single-sourcing’), and it is particularly helpful in processing large amounts of text.

Modular Documentation

In modular documentation, information is split into small units that are understandable while separated from a context. The base unit is called a ‘module’, which is a short, independent unit of information, usually containing one topic entity—in practice, answering one question such as ‘what’, ‘why’ or ‘how’. Since these modules can be organized in whichever order, modular documentation is non-hierarchical and non-linear.

Modular documentation is structured documentation (see ‘structured writing’) and it follows a selected architecture such as XML-based DITA. This architecture enables the processing of the structured information independently from the eventual publishing and presentation systems, and it is based on a markup language which enables the naming and organizing—conditionalizing—of information elements according to their content.

Single-sourcing

Single-sourcing enables the reuse of content in many forms. According to the principles of single-sourcing, content is created in such a form and format that it can be reused in program-wise different publications without significant rewriting. Single-sourcing is based on modular documentation and structured writing (see ‘modular documentation’ and ‘structured writing’), however, it is important to note that single-sourcing is a methodology and not a technology.

Single-sourcing saves time and money by reducing the amount of redundant, overlapping work. It helps to improve the usability of documentation through documentation standards or standardising of documentation. It also facilitates translation and localization.

Cross-media Publishing

In cross-media publishing, the same message is sent or content and services are offered through different media and different channels. The content published isn’t necessarily completely identical in the different channels; it can be modified according to, for example, the target audience or the method of presentation.

In cross-media publishing, information is stored in a generally readable format in a database from which the information is distributed to the different channels—for example, as an electronic file to a website or as a printed leaflet sent via mail. The data is stored without considering the eventual method of presentation or look. The style of the published material is selected according to its content and the channel used. Content producers mark important elements, such as headings and images, and based on these “markings”, the content can be shared and distributed through different media. The published material also contains metadata on its content, which then can be used for targeting the audience with content that matches their interests or matches the intended purpose of the publication.

In more targeted cross-media publishing solutions, the publication channels are divided into subchannels. The subchannel is selected, for example, based on user information or the produced content, or the intended terminal device (for example, to fit a particular reading device or phone model).

Sources

Satu Sevon-Nielsen
Satu.Sevon-Nielsen@dox.fi

-->