Glossary of technical writing terms

This glossary explains terms that are related to technical writing and software documentation. Possibly, the terms 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

A top of page

a-z index (a to z index)

See index.

access key

This has two meanings:

With Microsoft Windows, a key that is related to an underlined character on a menu, a command, or a dialog box.
With websites, a character key that can be pressed to select a hyperlink or a field in a form.

accessibility

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

AECMA Simplified English

See ASD Simplified Technical English.

application documentation

See documentation.

appendix

Text that is near the end a book. Usually, an appendix contains the following things:

Information that helps some people, but which other people do not need.
Information that is not important, but which some people want to know about.

An appendix is part of the end matter.

ASD Simplified Technical English (ASD-STE100)

A controlled language for the aircraft industry. Before issue 3, ASD Simplified Technical English was known as AECMA Simplified English.

audience analysis

Also known as 'user analysis' or 'audience research'. Identification of the requirements of users. See also task analysis; training needs analysis.

authoring memory

Software that helps technical authors to write consistently. Source text is stored in a database. When a technical author writes text that is similar to text in the database, the software supplies the stored text to the technical author. If the stored text is suitable, the technical author can use it. See also controlled language; controlled vocabulary; translation memory.

automated translation

See machine translation.

B top of page

back matter: The American English name for end matter.
back-of-the-book index: See index.
bibliography: A list of books, articles, web pages, or other documents. Usually, the documents in the list are related to the content of the primary document. For example, they contain background information.
browse sequence: A navigation method in online documentation. A browse sequence is similar in concept to a wizard. Users click a button or a hyperlink to view the next topic or the previous topic in a set of topics. Usually, the topics are read in sequence.
bulleted list: An unordered list that uses 'bullet points' or other marks to show the start of each item in the list. See also ordered list; numbered list.

C top of page

callout

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

Canadian binding

A type of binding for printed documents. The pages are held together with wire. The wire spine has a cover.

caption

A label for a graphic.

Cascading Style Sheet (CSS)

A set of rules that specify how a web browser displays an HTML page. The advantages of CSS instead of HTML formatting are as follows:

The style is controlled in one location, and changes are automatically applied to all HTML pages.
The file size of each HTML page is smaller (sometimes by 50% or more). Therefore, documents can be downloaded more quickly.
Accessibility is improved.

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

CBT

See e-learning.

comb binding

A type of binding for printed documents. The pages are held together with a circular plastic comb.

CHM Help

See compiled HTML Help.

CMS

See content management system.

CNL (controlled natural language)

See controlled language.

compiled HTML Help (CHM help)

A proprietary help system from Microsoft. Also known as CHM help, because of the file name extension. Compiled HTML Help is based on HTML.

computer translation

See machine translation.

computer-based training (CBT)

See e-learning.

concordance

See under index.

content management system (CMS)

Software for managing digital content such as websites. See also document management system; help authoring tool.

contents list

See table of contents.

context-sensitive help

Online documentation that has context sensitivity.

context-sensitivity

The ability of online documentation to respond dependent on a user's interaction with the software. Usually, a user presses the F1 key or a help button to view help about the active dialog box. See also context-sensitive help.

controlled language

A language that has limits on how grammar and words are used. The purpose is to make text as clear as possible. See also ASD Simplified Technical English; controlled vocabulary.

controlled natural language (CNL)

See controlled language.

controlled vocabulary

A set of terms that a technical writer is permitted to use. The purpose is to make text as clear as possible. See also ASD Simplified Technical English; controlled language.

copyright

The legal right to publish a document. An author automatically has the copyright of a document, but the author can assign copyright. See the Patent Office's Copyright section (www.ipo.gov.uk/copy.htm).

copywriting

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

crop (verb)

To remove part of a graphic.

cross-platform help

Online documentation that can be used on all software operating systems and all web browsers.

cross-reference

A direction from one part of a document either to another part of the document, or to a different document. In a printed document, a cross-reference usually contains a page number. In an online document, a cross-reference is usually a hyperlink.

CSS

See Cascading Style Sheet.

D top of page

DAISY: See Digital Accessible Information SYstem (DAISY).
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 Information Mapping. See Cover Pages' Darwin Information Typing-Architecture (DITA XML) (http://xml.coverpages.org/dita.html).
definition list: See glossary.
Digital Accessible Information SYstem (DAISY): A technical standard that is used to create accessible content. See the DAISY Consortium (www.daisy.org).
digital communication: See online documentation.
digital printing: Printing technology that does not use plate or film in the printing process, unlike litho printing. To compare 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 final disposal (destruction or archiving) in an organisation. See also document management system.
document management system: Software for document management. See also content management system.
documentation: Information that helps people to solve problems, to make decisions, and to do tasks efficiently. See also online documentation; reference manual; user guide.
documentation plan: A document that specifies the important parts of a documentation project. This term is equivalent to the term 'project plan'.
domain expert: See subject matter expert.

E top of page

e-help (ehelp): See online documentation.
e-learning: Self-study training material that is supplied electronically (usually, on the Internet). E-learning is also known as computer-based training (CBT), although this term is becoming less popular.
EasyEnglish: A particular type of international English from Wycliffe Associates (UK) (www.easyenglish.info/eewhatis.htm). See also Global English; Globish; Special English.
Easy Read: English that is written to help people who have learning difficulties. For guidelines that explain how to write in Easy Read, see 'How to use Easy Words and Pictures (Easy Read Guide)', first published by the Disability Rights Commission (www.library.nhs.uk/SpecialistLibrarySearch/Download.aspx?resID=187517).
Electronic Performance Support System (EPSS): An electronic system that is immediately available and that helps people to do their business tasks. Unlike online documentation for a single software product, an EPSS usually supports all of an organisation.
electronic publications: See online documentation.
embedded help: Documentation that is part of the software. Embedded help appears directly on a window, a screen, or a tab. It cannot be opened independently from the software. See also Help.
embedded index: An index that is created as part of an electronic document. A technical writer marks index entries in the text, and the software automatically creates locators.
end matter: Supplementary information that comes after the primary text in a printed book. In the context of software documentation, end matter usually 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).

F top of page

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

G top of page

Global English: A particular type of international English. See also EasyEnglish; Globish; Special English.
Globish: A particular type of international English. See also EasyEnglish; Global English; Special English.
glossary: An alphabetic list of terms. Each term is explained. Essentially, a glossary is a small dictionary that helps readers to understand the meaning of the terms in a document.
graphic: An item of art, for example, a screen shot, a diagram, a flow chart, or a photograph.

H top of page

hard copy: All forms of physical documentation, such as printed user guides, laminated 'cheat sheets', wall charts, and reference manuals.
header: Information that is repeated at the top of each page or online documentation topic. For example, headers in printed documentation show the chapter title and page number. See also footer.
Help (Help file, Help screen): See context-sensitive help.
help authoring tool (HAT): Software that is used to create online documentation. See HAT Matrix (www.hat-matrix.com).
hot spot: On a screen, an area on a graphic that responds to the pointer.
house style: See style guide.
hyperlink: In online documentation, a link from one part of a document to another part of a document or to another document. Usually, the link is coloured text, or a small graphic. A user clicks the link to view the new location.
hypermedia: See online documentation.
hypertext media: See online documentation.

I top of page

idiom: A group of words that has a different meaning from the usual meaning of the separate words. For example, 'out of the blue' is an idiom that means 'unexpectedly'.
index (compared with concordance): An ordered list (usually alphabetic) of terms. Index entries contain cross-references (page numbers or hyperlinks) to pages or topics in a document. For an example, see the index to this website.; An index and a concordance are both ordered lists, but functionally, they are different. A concordance contains only terms that are in a document. Usually, these terms are product names, technical terms, and acronyms. An index captures the meaning of the topics in a document. Possibly, some index entries do not appear in the primary text of a document. For example, an index entry for 'data output' directs readers to topics about reports and about saving data, but the term 'data output' does not appear in either of the topics.; See also table of contents.
info mapping: See Information Mapping.
information architecture: See information design.
information design: For all practical purposes, this is another name for technical writing (technical authoring, technical communication). See also instructional design.
Information Mapping: A proprietary method for analysing, organising, and presenting information. A type of structured authoring.
instant translation: See machine translation.
instruction manual: See reference manual; user guide.
instructional design: The design of instructional materials such as training courses, e-learning systems, and user guides. See also information design.
instructions: See procedure.
international English: English that is optimised for an international audience. See also EasyEnglish; Global English; Globish; Special English; TechScribe's international English website.
internationalised English: An alternative name for international English.
ISO/IEC 15910:1999: 'Information technology—Software user documentation process'. This standard can be used as a contractual document to specify the process between the organisation that is developing the documentation and the organisation that is buying it.
ISO/IEC 18019:2004: 'Software and system engineering—Guidelines for the design and presentation of user documentation for application software'. This old international standard was replaced by ISO/IEC 26514:2008.
ISO/IEC 26514:2008: 'Software and system engineering—Requirements for designers and developers of user documentation'. This international standard replaces ISO/IEC 18019:2004.
ISTC: Institute of Scientific and Technical Communicators (www.istc.org.uk). A professional organisation for technical communicators. See also STC.

J top of page

jargon: Technical language that is used in a profession, or by a group of people. Jargon is suitable in some documentation. For example, in a reference manual for SQL programmers, terms such as 'table', 'entity', and '3^rd Normal Form' are suitable. However, it is not correct to use such terms for the average user of business software.
JavaHelp: An open source system from Sun for creating online documentation (http://java.sun.com/javase/technologies/desktop/javahelp/).
just-in-time printing: See print on demand.

K top of page

keyword (or key word): A word or phrase that is related to an online topic. Keywords are specified by the technical writer. Users can search for keywords, and if that keyword exists, one or more topics are shown to the user. A keyword is the online equivalent of an index entry.
knowledge acquisition: Strategies, tools, and methods for finding information, specially information that subject matter experts know. Knowledge acquisition is one of the most important parts 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 the BCS article 'Working smarter not harder' (www.bcs.org/server.php?show=ConWebDoc.14285).

L top of page

l10n: A jargon term for localisation. The word localisation contains 12 letters. Between the first letter (l) and the last letter (n) are 10 other letters.
LaTeX: A typesetting system that is used to create documents that have high-quality typography.
Lay-flat binding: A type of binding for printed documents. The pages are held together with flexible adhesive tape.
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 language. Translation of text is a large part of this. Analogies, symbols, icons, and colours must be evaluated and possibly changed, because their meanings can change across cultures.
locator: In a printed index, a page number that comes after a heading or a subheading, and which tells a reader where to find information about the heading or the subheading. In an online index, no page number exists. Instead, the heading or the subheading is a hyperlink.

M top of page

machine translation (MT)

The automatic translation of text using only software without the help of a translator. See also translation memory.

manual

See reference manual.

marcomms

See marketing communications.

marketing communications (marcomms)

An organisation's methods of communication with its customers and prospects. Although some technical writers create documents for marketing communications, copywriting and technical writing are different, as we show in 'Copywriting and technical writing compared'.

metadata

Data about data. For example, metadata about a book includes the price, the name of the author, and the ISBN.

minimalism

An action-based and task-oriented strategy to documentation. Minimalism gives emphasis to what readers must do, and it excludes information that is not important. The basic principle is task-orientation. Brevity is important, but only because it can help task-oriented activity. Minimalism has nothing to do with creating thin manuals by excluding important information.

Carroll introduced the term 'minimalism' in the early 1980s. He specifies 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.

MT

See machine translation.

multimedia

A collective term for text, graphics, animation, and interactive content.

N top of page

numbered list: An ordered list that uses numbers to show the sequence of items in the list. See also bulleted list; unordered list.

O top of page

online documentation: Documentation that is designed to be read from a screen. Usually, online documentation contains context-sensitive help. Online documentation is separate from the software, unlike embedded help.
online help: See online documentation.
on-screen documentation: See online documentation.
ordered list: A list in which the sequence of items is important. An ordered list does not necessarily contain sequence characters. For example, an index is an ordered list, but it is not a numbered list. See also bulleted list; unordered list.

Ptop of page

PDF (Portable Document Format): A file format that Adobe developed. PDF is an open standard named ISO 32000. See 'Adobe Portable Document Format' (www.adobe.com/products/acrobat/adobepdf.html).
perfect binding: A type of binding for printed documents. The pages are glued at one edge.
phrasal verb: A type of verb that has two words. Usually, the meaning of the verb is different from the usual meaning of the separate words. Usually, the parts of the verb can be separated by a noun. For example, 'carry out' is a phrasal verb. "He carried his job out well" means "he did his job well".
plain English: English that is written as clearly as possible.
pop-up help: See pop-up window.
pop-up window: In context-sensitive help, a small secondary window that appears when a user clicks a link.
Portable Document Format: See PDF.
preferred term: A term that is used in preference to another equivalent term. For example, at TechScribe, we use 'user guide' instead of 'user manual'. Therefore, the preferred term is 'user guide'. See also controlled vocabulary.
preliminary matter (prelims): An alternative name for front matter.
print on demand (printing on demand): A method for printing a small number of documents only when they are needed, using digital print technology.
procedure: A list of steps that a user does to complete a task. Sometimes, it is suitable to include information about result of a user's action, but usually, descriptive text is best avoided. See also process.
process: A description of a system. Possibly, none, one, or many users are involved. The focus is on how the system operates, not on what users do. See also procedure.

Qtop of page

QuikScan: A format that makes printed documents and online documents more usable. QuikScan uses numbered list items for summaries in the document. The numbers are related to numbers in the primary part of the text. See http://quikscan.org.

R top of page

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

S top of page

saddle stitch: A type of binding for printed documents. The pages are stapled together.
sans serif (compared with serif): A serif is a small projection on a character. Many traditional typefaces have serifs. A sans serif typeface is is a typeface that does not have projections.; Usually, for online documentation, a sans serif typefaces is better than a serif typeface, because serifs do not display well with current display resolutions. For printed documentation, either serif typefaces or sans serif typefaces are satisfactory.
screen capture: See screen shot.
screen shot: A copy of the content of a screen. Frequently, a screen shot is cropped to show only the important parts of the screen. See also graphic.
Section 508: US law that came into effect in June 2001. Section 508 requires that all IT products (including their documentation) that are sold to US government organisations 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 creating documentation. Single sourcing can be used when more than one item of documentation is necessary for a product. The components of all the documents are written in one source file. The writers of the source file specify which components are required for each item of documentation.
software documentation: See documentation.
Special English: A particular type of international English from Voice of America (www.voanews.com/specialenglish/about_special_english.cfm). See also EasyEnglish; Global English; Globish.
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 applies engineering principles to 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 usually contains information about the sentence style, layout, typefaces, captions, headers, and other parts 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.
subject matter expert (SME): A person who has detailed knowledge about a subject. Possibly, the knowledge is tacit knowledge.
syntactic cue: A part of language that helps a reader to identify parts of speech and to analyse the structure of a sentence.

T top of page

table of contents

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

In printed documentation, a list of chapters and subheadings with their related page numbers. The sequence of the list is the same as the sequence of the headings in the document. The table of contents is usually at the front of the document.
In online documentation, a list of topics with hyperlinks to the topics. Usually, the topics are put into groups of related information, and there is a hierarchy of expandable and collapsible headings. Usually, the table of contents appears as a navigation pane on the left side of the help window.

U top of page

UA: See user assistance.
UI: See user interface.
unordered list: A list in which the sequence of items is not important. Sometimes, an unordered list is a bulleted list. See also numbered list; ordered list.
usability: A quality attribute that assesses how easy user interfaces are to use (according to Jakob Nielsen, www.useit.com/alertbox/20030825.html). Usability is specified by five quality components: learnability, efficiency, memorability, errors, and satisfaction. See also accessibility.
user analysis: An alternative name for audience analysis.
user assistance (UA): Techniques and technologies to make working with software a better experience. These include online Help, wizards, websites, printed documentation, and improvements to the application user interface (based on text supplied by WritersUA/WinWriters, www.writersua.com).
user guide: A document that explains how to use software to do procedures. It answers the question, "how do I…?" See also reference manual; task-based documentation.
user interface (UI): The parts of a system that a person sees and uses to interact with the system. A user interface includes hardware such as a keyboard and a mouse. Frequently, the term user interface means the content that appears on a screen.
user instructions: See procedure.

V top of page

vocabulary list: See glossary.

W top 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. For excellent information about white papers, see www.thatwhitepaperguy.com.
white space: An empty area on a page or on a screen. White space does not always have a white colour. Its defining feature is that it does not contain text or graphics.
WinHelp: An early type of online documentation from Microsoft.
wire binding: A type of binding for printed documents. The pages are held together with a coil of wire.
word list: See glossary.
worldwide English: See international English.

X – Z top of page

XML: See Extensible Markup Language (XML).

RSS feed