Glossary of technical writing terminology

This glossary explains terms that are related to technical writing and software documentation. The terms may have other meanings in different contexts.

A B C D E F G H I J K L M N O P–Q R S T U V W X–Z

Atop of page

a-z index (a to z index)

Generally, synonymous with the term 'index' (although not every index is an a-z index).

access key

This has two different meanings:

With Microsoft Windows generally, a key that corresponds to an underlined character on a menu, command, or dialogue box.
In web site design, a character key that can be pressed to select a web link or field in a form.

accessibility

How accessible a product is. The level to which people with disabilities can use a product. (A product might be software, services, buildings). See also Section 508; usability.

AECMA Simplified English

See ASD Simplified Technical English.

appendix

A section of text that is related to material in book, but which typically does not contain essential information. Often, an appendix provides supplementary information that some people find useful, but which many people would find irrelevant. An appendix forms part of the end matter.

ASD Simplified Technical English™

A controlled language that is used in the aircraft industry. Previously known as AECMA Simplified English. For more information, see 'Beyond Plain English'.

audience analysis

Also known as 'user analysis' or 'audience research'. Identification of the needs of users. If writers know for whom they are writing, they can target the material appropriately. See also task analysis.

Btop of page

back-of-the-book index

Generally, synonymous with the term 'index' (although not every index is a back-of-the-book index).

back matter

The American English name for end matter.

bibliography

A list of books, articles, web pages or other writings that are:

Referenced in a document
Related to the content of a document (for example, additional background material).

browse sequence

A navigation method that is used in online documentation. It is similar in concept to a Wizard. Users can click on a button or text to view the next (or previous) topic in a set of topics that are ideally read in a specific sequence.

Ctop of page

callout

Text and a line that points to an area on a graphic image. For example:

caption

A label for a graphic image or a table.

cascading style sheet (CSS)

A set of rules that define how a web browser should display an HTML page. Major advantages of using CSS rather than HTML formatting are:

Style is controlled globally and any changes are propagated to all HTML pages.
HTML code is physically smaller, often by 50% or so, resulting in faster download.
Accessibility is improved.

The international CSS standards are available from www.w3.org.

CBT

An early form of e-learning.

CHM Help

See compiled HTML help.

CMS

See content management system.

compiled HTML help (CHM help)

A proprietary help system from Microsoft. Also known as CHM help (because of the file name extension). It is based on HTML.

computer-based training (CBT)

An early form of e-learning.

concordance

See under index.

content management system (CMS)

A software system for managing digital content. Typically, a CMS is used for web sites and enterprise content. Some help authoring tools are positioned as CMSs. See also document management system.

contents list

See table of contents.

context-sensitivity (context-sensitive)

The ability of online documentation systems to react differently according to the state of the user's interaction with the software application. Typically, a user presses the F1 key or a help button to obtain help about the current dialogue box. Field-level help is sometimes also provided. For more information, see 'Context-sensitive help'.

controlled language

Language that has restrictions placed on how grammar and vocabulary is used. The aim is to ensure that the text is clear and unambiguous. See also ASD Simplified Technical English.

copyright

The legal right to publish a document. Copyright automatically resides with an author of a work, unless the author assigns copyright. See the Patent Office's Copyright section (www.ipo.gov.uk/copy.htm).

copywriting

The art of creating content (or 'copy'). Generally, the term refers to writing in the literary sense, rather than the engineered language that technical writers produce. For example, copywriters produce text for journals, magazines, brochures, and other forms of marketing communications.

cross-platform help

Online documentation that can be used on all software platforms (operating systems, and web browsers).

CSS

See cascading style sheet.

Dtop of page

Darwin Information Typing-Architecture (DITA): An XML-based architecture for structured authoring and the delivery of information. It uses the concepts of 'typed topics', which is similar to 'information types' in the Information Mapping methodology. See Cover Pages' Darwin Information Typing-Architecture (DITA XML) (http://xml.coverpages.org/dita.html).
definition list: See glossary.
digital communication: See online documentation.
digital printing: Printing technology that does not use plate or film in the printing process, unlike litho printing. For a comparison of these methods, see 'Digital printing for software manuals'.
DITA: See Darwin Information Typing-Architecture.
document management: The management of (usually electronic) documents from their creation to their eventual disposal (destruction or archiving) within an organisation. See also document management system.
document management system: A software solution for document management. See also content management system.
documentation: Material that helps people to overcome problems, make decisions and perform tasks more efficiently. See also online documentation; reference manual; user guide.
documentation plan: A document that defines the essential elements of the documentation project. This ISO/IEC 15910 term is equivalent to the term 'project plan'.

Etop of page

e-help (ehelp): See online documentation.
e-learning: Self-study training material that is provided electronically (typically, over the Internet). E-learning is also known as computer-based training (CBT), although this term is losing popularity.
Electronic Performance Support System (EPSS): An electronic system that is immediately available and that helps people to perform their business activities. Unlike online documentation for a single software product, it typically supports an entire organisation.
electronic publications: See online documentation.
embedded help: Documentation that is provided as part of the software application, and which appears directly on a window, screen, or tab. See also Help.
embedded index: An index that is created as an integral part of an electronic document. An author marks index entries within the text, and the software automatically generates locators (page numbers for printed documents, and hyperlinks for online documentation.
end matter: Supplementary information that comes after the main text in a printed book. Within the context of software documentation, it typically includes appendices, the index and glossary. See also front matter.
Extensible Markup Language (XML): A markup language used for structured authoring. See Cover Pages' Extensible Markup Language (XML) (http://xml.coverpages.org/xml.html).

Ftop of page

FlashHelp: A Flash-based online documentation format from Adobe. See also WebHelp.
font: A specific instance of a typeface. For example, 'Times 12pt Bold'.
footer: Information that is repeated at the end of every page or online documentation topic. For example, the footers on this web site all contain a copyright statement. See also header.
front matter: In a printed document, material that comes before the main text. Typically, in software documentation, this consists of legal notices, copyright information, publication date and so on. Usually, a table of contents comes after this. See also end matter.

Gtop of page

glossary: An alphabetic list of words and phrases (as in this web page). Each word or phrase is defined or explained. In essence, a mini-dictionary that helps readers to understand the meaning of the terms used in a document.
graphic: An item of artwork, such as a screenshot, a diagram, a flowchart, or a photograph.

Htop of page

hard copy: All forms of physical documentation (as opposed to electronic documentation that is displayed on a screen). Typical forms of hard copy include printed user guides, laminated 'cheat sheets', wall charts and reference manuals.
header: Information that is repeated at the top of every page or online documentation topic. For example, headers in printed documentation might show the chapter title and page number. See also footer.
Help (Help file, Help screen): A synonym for online documentation that uses context-sensitivity. See also embedded help.
help authoring tool (HAT): Software that is used to create online documentation. See HAT Matrix (www.hat-matrix.com).
house style: See style guide.
hypertext media: See online documentation.

Itop of page

index (compared with concordance): An ordered list (typically, alphabetic) of words and phrases. Index entries contain cross-references (page numbers or links) to pages or topics in a document. For an example, see the index to this web site.; An index and a concordance are superficially similar (both are ordered lists). Functionally, they are very different. A concordance lists only words or phrases that appear in a document. Typically, these are product names, technical terminology, acronyms and so on. An index captures the essential meaning of the topics in a document. Some index entries may not appear in the body of the document itself. For example, there may be an index entry, 'data output'. This might direct readers to topics that deal with printing reports and exporting CSV data. The term 'data output' might not appear in either of these topics.; See also table of contents.
info mapping: See Information Mapping.
information architecture: See information design.
information design: For all practical purposes, just another name for technical writing (or technical authoring, technical communication, communications design). See also instructional design.
Information Mapping^®: A proprietary methodology for systematically analysing, organising and presenting information. A form of structured authoring.
instruction manual: See user guide.
instructional design: The design of instructional materials such as training courses, e-learning systems, and procedure guides. See also information design.
instructions: See procedure.
ISO/IEC 15910:1999: 'Information technology—Software user documentation process'. This standard can be used as a contractual document to define the process between the organisation that is developing the documentation and the organisation that is buying it.
ISO/IEC 18019:2004: 'Guidelines for the design and presentation of user documentation for application software'.
ISTC: Institute of Scientific and Technical Communicators (www.istc.org.uk). A professional organisation for technical communicators. See also STC.

Jtop of page

jargon: Technical language that is used by a particular profession or group of people. It is not wrong to use jargon in documentation. For example, in a reference manual for SQL programmers, terms such as 'table', 'entity', and '3^rd Normal Form' are acceptable. However, it is not appropriate to use such terms for the average user of business software.
just-in-time printing: See print on demand.

Ktop of page

keyword (or key word): A word or phrase that is associated with an online topic. Keywords are defined by the author. Users can search for keywords, and if that keyword has been defined, one or more topics are presented to the user. A keyword is the online equivalent of an index entry.
knowledge acquisition: Strategies, tools, and techniques for obtaining information, particularly information that is in the heads of subject matter experts. This is one of the most important aspects of technical documentation. See Epistemic's 'Knowledge Acquisition' section (www.epistemics.co.uk/Notes/63-0-0.htm).
knowledge elicitation: See knowledge acquisition.
knowledge management (KM): A superset of technical communication. Knowledge management is "doing what is needed to get the most out of the collective knowledge resources in a company" (see BCS article 'Working smarter not harder' (www.bcs.org/server.php?show=ConWebDoc.14285).

Ltop of page

LaTeX: A typesetting system that uses markup language to produce documents that have high-quality typography.
list of contents: See table of contents.
litho printing: The 'traditional' method of producing printed documentation. For low print volumes, digital printing is a better option. For a comparison, see 'Digital printing for software manuals'.
localisation: The process of converting a document from one language into another. Translation of text is a major part of this. Other things that must be evaluated and possibly modified include analogies, symbols, icons and colours, since their meaning can vary across cultures.

M – Ntop of page

manual

See reference manual.

marketing communications (marcomms)

An organisation's methods of communication with its customers and prospects. Typically, this is pre-sales communication and is related to advertising and brand promotion. Although some technical writers produce marketing communications, marcomms and technical communication are different, as we discuss in 'Copywriting and technical writing compared'.

minimalism

An action-based and task-oriented approach to documentation. It emphasises what users should do and it avoids swamping readers with information that is not relevant. The central principle is task-orientation. Brevity is a key element, but only because it can aid task-oriented activity. Minimalism has nothing to do with producing thin manuals by omitting vital information.

Carroll introduced the term 'minimalism' in the early 1980s. He states the basic principles as:

Choose an action-oriented approach.
Anchor the tool in the task domain.
Support error recognition and recovery.
Support reading to do, study and locate.

moiré

An interference pattern that appears in screen shots.

Otop of page

online documentation (online help): Documentation that is designed to be read from a computer screen. Usually, it contains context-sensitive help. It is separate from the software application, unlike embedded help.
on-screen documentation: A synonym for online documentation.

P–Qtop of page

PDF (Portable Document Format): A file format originally devised by Adobe. Adobe is working to submit PDF 1.7 to ISO for approval as an open standard named ISO 32000. See 'Adobe Portable Document Format' (www.adobe.com/products/acrobat/adobepdf.html).
preliminary matter (prelims): An alternative name for front matter.
print on demand (printing on demand): A methodology that allows for the printing of low volumes of documentation only when it is needed, using digital print technology.
procedure: A list of steps that a user takes to perform a task. Occasionally, it is appropriate to include information about result of a user's action, but in general, descriptive text is best avoided. See also process.
process: A description of a system. None, one or many users may be involved. The focus is on how the system operates, not on what users do. See also procedure.

Rtop of page

reference manual: A document that explains the features of a software product. Usually, every dialog box, screen, field, tab, and button is explained. It answers the question, "what is x?". See also user guide.
running foot: See footer.
running head: See header.

Stop of page

sans serif (compared with serif): A serif is a small projection on a character. Many traditional typefaces use these. A sans serif typeface is one that does not have any projections.; Generally, for online documentation, only sans serif typefaces should be used. This is because serifs do not display well with current display resolutions. For printed documentation, either serif typefaces or sans serif typefaces can be used.
section 508: US legislation that came into force in June 2001. It requires that all IT products (including their documentation) that are sold to US government agencies are accessible to people with disabilities.
serif: See under sans serif (compared with serif).
simplified English: An English controlled language, such as ASD Simplified Technical English and Wycliffe Associates' EasyEnglish (www.easyenglish.info/about-us/articles/communicator.htm).
single source publishing: See single sourcing.
single sourcing: A method of producing documentation that can be used when more than one item of documentation is needed for a product. The components of all the documents are written in one single source file. The writers of the source file define which components are required for each of the various documents.
STC: Society for Technical Communication (www.stc.org). A professional organisation for technical communicators. See also ISTC.
structured authoring (structured writing): A method of writing that helps to bring engineering principles to the construction of documentation. Information is 'typed' (for example, 'fact', 'concept', 'data value', 'procedure'). Rules specify the structure of a document. See also controlled language; Extensible Markup Language (XML); Information Mapping.
style guide: Rules and guidelines that tell authors how to write documents. A style guide typically contains information about the sentence style, layout, typefaces, captions, headers, and other elements of a document. See also style sheet.
style sheet: Rules that specify how a computer system displays the content of an electronic document. See also cascading style sheet; style guide.

Ttop of page

table of contents

A method of accessing the information that is contained in a document.

In printed documentation, a list of chapters and subheadings with their associated page numbers. The order of the list matches the order of the headings in the document. The table of contents typically appears at the front of the document.
In online documentation, a list of topics with links to the topics. Typically, the topics are organised into groups of related information, and there is a hierarchy of expandable and collapsible headings. The table of contents typically appears as a navigation pane on the left side of the help window.

Utop of page

UA: See user assistance.
usability: A quality attribute that assesses how easy user interfaces are to use (according to Jakob Nielsen, www.useit.com/alertbox/20030825.html). It is defined by five quality components: learnability, efficiency, memorability, errors, satisfaction. See also accessibility.
user analysis: An alternative name for audience analysis.
user assistance (UA): A variety of techniques and technologies to make working with software a better experience. These include online Help, wizards, web sites, printed documentation, and improvements to the application user interface (based on text supplied by WritersUA/WinWriters, www.writersua.com).
user guide: A document that deals mainly with work procedures. It explains how to use software to do a job. It answers the question, "how do I…?" See also reference manual.
user instructions: See procedure.

Vtop of page

vocabulary list: See glossary.

Wtop of page

WebHelp: A cross-platform online documentation system from Adobe. It has similar functionality to compiled HTML help. See also FlashHelp.
white paper: A detailed or authoritative report.
white space: Blank areas on a page or on a computer screen. White space may not necessarily be pure white; its defining feature is that it does not contain text or graphics.
WinHelp: An early form of online documentation from Microsoft. Now superseded by compiled HTML help.
word list: See glossary.

X – Ztop of page

XML: See Extensible Markup Language (XML).

RSS feed