Following 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.
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.
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.
A navigation aid which helps users to keep track of their location within a document.
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.
Text providing information about a feature displayed in an image.
Compiled HTML file. The compressed version of the online help format of Microsoft Compiled HTML Help.
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.
Where the relevant help topic is accessed directly from the software.
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.
A set of documents provided in any format. For example, online user guides, printed policies and procedures, audio or video guides.
Tips that are integrated into the user interface right next to the part of the screen that it applies to.
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.
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.
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.
A visual representation used to assist in the understanding a product.
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.
Presenting information in a way that makes it understandable and accessible.
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’.
User assistance and documentation that is available through your organisation’s intranet, extranet or website.
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.
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.
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.
A layout and style guide used within a technical authoring application. Using a template ensures consistency.
Table of Contents. Lists usually found at the front of a book or document, used for navigating documentation.
The ease of use of documentation. This refers to how easily a user can find the information they need.
Any individual using an application or product. There may be different levels of user if access permission varies according to user authority.
Writing documentation in a style that addresses the needs of the main audience first.
A technical communication document intended to give assistance to people using a particular system.