Technical Authoring. 30 terms you should know.

technical authoringFollowing on from my recent blog post discussing the use of Plain English by technical authors, I have compiled a list of commonly used technical authoring terms. Have a look and test your knowledge.

Accessibility

The degree to which documentation is available to as many people as possible. This refers to both to the inclusive practice of removing barriers that prevent access to websites by people with disabilities and ease of understanding. When online help is correctly designed, developed and edited, all users have equal access to information and functionality and ease of understanding.

Active voice

Where the subject of a sentence performs the action stated by the verb. For example, ‘Sally baked the cake’. Using the passive voice changes this statement to ‘The cake was baked by Sally.’ It is generally accepted that the active voice should be used in technical authoring.

Breadcrumbs

A navigation aid which helps users to keep track of their location within a document.

Browse sequence

A navigation tool which helps a user move through documentation in a logical order. As the user clicks the browse back and forward arrow they move through the documentation.

Callout

Text providing information about a feature displayed in an image.

CHM help

Compiled HTML file. The compressed version of the online help format of Microsoft Compiled HTML Help.

CMS

Content Management System. A computer application that allows publishing, editing and modifying content, organising, deleting as well as maintenance from a central interface. Such systems of content management provide procedures to manage workflow in a collaborative environment.

Context sensitive help

Where the relevant help topic is accessed directly from the software.

CSS

Cascading Style Sheets.
A style sheet language used to format the look of a document which is written in markup language (such as HTML). The CSS is held separately from the content of the document allowing for different CSS to be applied to be for different outputs of content.

Documentation

A set of documents provided in any format. For example, online user guides, printed policies and procedures, audio or video guides.

Embedded help

Tips that are integrated into the user interface right next to the part of the screen that it applies to.

FTP

File Transfer Protocol. Used to transfer computer files from one host to another, usually over the internet. A commonly used method of delivery for large documentation files.

Glossary

An alphabetical list of terms and their definitions. Usually found at the end of a book or document and includes uncommon or specialised terms.

GUI / UI

User Interface. The means in which a person controls a software application or hardware device. An intuitive user interface encourages interaction with an application.

Hyperlink

A navigation tool used to automatically link one document to another. The link is usually followed by tapping, clicking or hovering over a point in a document.

Illustration

A visual representation used to assist in the understanding a product.

Index

A list of words or phrases used within a book or document. Traditionally an index is found at the back of a book. Each word or phrase in the index has a page number referenced where information can be found in the book.

Information design

Presenting information in a way that makes it understandable and accessible.

Knowledge centre

A single holding place for all of your company documentation.  This is usually held online either on the internet or your corporate intranet.

Mobile first development

Documentation and content design with mobile platforms being considered before desktop. This is also known as ‘Progressive enhancement’.

Online help

User assistance and documentation that is available through your organisation’s intranet, extranet or website.

Plain English

Also refered to as ‘plain language’ or ‘plain words’. A form of communication that emphasises clarity, brevity and the avoidance of technical language. It is important to use Plain English when technical authoring.

Readability

The ease with which text can be read and understood. Reading ease scores, calculated using tools such as the Flesch Reading Ease Formula, can be used to measure the readability of a document.

Screenshot

Also known as a ‘screen capture’ or ‘screengrab’. A screenshot is an image taken from the software being documented. This is useful when indicating where a function can be found on a screen.

Template

A layout and style guide used within a technical authoring application. Using a template ensures consistency.

ToC

Table of Contents. Lists usually found at the front of a book or document, used for navigating documentation.

Usability

The ease of use of documentation. This refers to how easily a user can find the information they need.

User

Any individual using an application or product. There may be different levels of user if access permission varies according to user authority.

User centred authoring

Writing documentation in a style that addresses the needs of the main audience first.

User guide

A technical communication document intended to give assistance to people using a particular system.

Technical Authoring. 30 terms you should know.

Leave a Reply

Your email address will not be published. Required fields are marked *