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.

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:
Callouts
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 '3rd 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.

MNtop 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:
  1. Choose an action-oriented approach.
  2. Anchor the tool in the task domain.
  3. Support error recognition and recovery.
  4. Support reading to do, study and locate.
moiré
An interference pattern that appears in screen shots.
Moiré on a scrollbar
See also 'How to remove moiré from 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.

PQtop 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.
Serifs and no serifs (sans serif)
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.
See also index.
task analysis
The process of defining the tasks that people perform when they interact with a (software) system. See also audience analysis; knowledge acquisition.
task-based documentation
Documentation that focuses on the tasks that users must perform within the context of their working environment. This contrasts with documentation that is based on the structure of a software product.
technical authoring
An alternative term for technical writing.
technical communication
The communication of a technical message. The term is often used loosely as an alternative name for technical writing, but it includes all forms of technical instruction, such as technical illustration, multimedia design, and e-learning.
technical documentation
See documentation.
technical writing
The communication of a technical message, primarily using text-based material. See also technical authoring; technical communication.
terminology list
See glossary.
translation memory (translation memory system)
A software tool for aiding human translators. A translator translates words and phrases from a source language into a target language (the translation). When those words and phrases re-appear in new source text, the previous translation is automatically offered to the translator, who can use it or modify it as necessary. If documentation is translated, significantly reduced translation costs can be obtained by ensuring that the source documentation conforms to a controlled vocabulary (or better, to a controlled language).
typeface
The name of the design for a set of fonts. For example, 'Times New Roman'. The terms font and typeface are often used incorrectly used as synonyms. See 'Microsoft typography' (www.microsoft.com/typography/default.mspx) and 'Choosing & using type' (www.will-harris.com/use-type.htm)

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.

XZtop of page

XML
See Extensible Markup Language (XML).
RSS feed