Technical Writing Glossary¶

A comprehensive reference of terms, concepts, and jargon used in technical communication.

A¶

Accessibility: The practice of making content usable by people with disabilities, including those using assistive technologies.
Active voice: A sentence construction where the subject performs the action. "The user clicks the button" versus "The button is clicked by the user."
Admonition: A formatted callout box used to highlight warnings, notes, tips, or other important information.
API (Application Programming Interface): A set of protocols and tools that allow software applications to communicate with each other.
Audience analysis: The process of identifying and understanding the characteristics, needs, and expectations of your readers.

B¶

Boilerplate: Standardized text that can be reused across multiple documents with little or no change.
Breadcrumb: A navigation element showing the user's location within a document hierarchy.

C¶

CCMS (Component Content Management System): A system for managing documentation at the component level rather than the document level.
Chunking: Breaking content into smaller, manageable pieces that are easier to read and understand.
Conceptual documentation: Content that explains ideas, theories, or background information rather than procedures.
Conditional text: Content that appears or is hidden based on specific conditions, such as audience or output format.
Content reuse: Using the same content in multiple locations to maintain consistency and reduce maintenance.
Content strategy: The planning, development, and management of content throughout its lifecycle.

D¶

DITA (Darwin Information Typing Architecture): An XML-based architecture for authoring, producing, and delivering technical information.
Docs as code: A methodology that applies software development practices to documentation, including version control and automation.
Document type: A category of documentation defined by its purpose, such as tutorials, reference guides, or release notes.

E¶

End user: The person who ultimately uses a product or reads documentation.
Error message: Text that appears when something goes wrong, explaining the problem and ideally how to fix it.

F¶

Front matter: Metadata at the beginning of a document, often in YAML format, containing title, description, and other properties.

G¶

Getting started guide: Documentation that helps new users begin using a product quickly.
GUI (Graphical User Interface): The visual elements users interact with, including buttons, menus, and windows.

H¶

Help system: Integrated documentation accessible within an application.
How-to guide: Task-oriented documentation that explains how to accomplish a specific goal.

I¶

IA (Information Architecture): The structural design of information spaces, including organization, labeling, and navigation.
Inline help: Brief assistance text that appears within the user interface, such as tooltips or placeholder text.

J¶

JATS (Journal Article Tag Suite): An XML format for scholarly and scientific publishing.

K¶

Knowledge base: A centralized repository of information, often including FAQs, troubleshooting guides, and how-to articles.
Knowledge management: The process of creating, organizing, and maintaining organizational knowledge.

L¶

Localization: Adapting content for a specific locale, including translation, cultural adaptation, and format changes.
Linting: Automated checking of content for errors, style violations, or other issues.

M¶

Markdown: A lightweight markup language using plain text formatting syntax.
Metadata: Data that describes other data, such as document properties, tags, or categories.
Microcopy: Short pieces of text in a user interface, such as button labels, error messages, and tooltips.
Minimalism: A documentation approach focused on providing only essential information to complete tasks.

N¶

Navigation: The system that allows users to move through and find content.

O¶

Onboarding: The process of helping new users learn to use a product effectively.
OpenAPI (Swagger): A specification for describing REST APIs in a machine-readable format.

P¶

Persona: A fictional character representing a typical user, used to guide content decisions.
Plain language: Writing that is clear, concise, and easily understood by the intended audience.
Procedural documentation: Step-by-step instructions for completing specific tasks.

Q¶

Quick reference: A condensed document providing essential information at a glance.
Quick start guide: Abbreviated documentation helping users begin using a product immediately.

R¶

README: A document providing essential information about a project, typically in a code repository.
Reference documentation: Comprehensive information about APIs, commands, or system components.
Release notes: Documentation describing changes, fixes, and new features in a software release.
Restructured text (RST): A markup syntax used primarily in Python documentation.

S¶

SDK (Software Development Kit): A collection of tools, libraries, and documentation for building software.
SEO (Search Engine Optimization): Practices that improve content visibility in search results.
Single sourcing: Creating content once and publishing it in multiple formats or locations.
SME (Subject Matter Expert): A person with deep knowledge in a specific area who provides information for documentation.
Snippet: A reusable piece of content that can be inserted into multiple documents.
Style guide: A set of standards for writing and formatting documentation.

T¶

Technical communication: The practice of conveying complex information to specific audiences.
Technical writer: A professional who creates documentation and other technical content.
Template: A pre-formatted document structure that can be reused.
TOC (Table of Contents): A structured list of sections or chapters in a document.
Topic: A self-contained unit of information focused on a single subject.
Topic-based authoring: Writing content as standalone topics that can be assembled in various ways.
Translation memory: A database of previously translated content used to improve translation consistency and efficiency.
Tutorial: Educational content that teaches users how to accomplish something through guided practice.

U¶

UI text: Words that appear in a user interface, including labels, messages, and instructions.
Usability: The ease with which users can accomplish their goals with a product or documentation.
User assistance: Content and features that help users use a product, including documentation, help systems, and support.
User experience (UX): The overall experience a person has when interacting with a product or content.
UX writing: Creating user-facing text in digital products to guide users and improve their experience.

V¶

Version control: A system for tracking changes to files over time, enabling collaboration and history management.
Voice and tone: The personality and emotion conveyed through writing.

W¶

White paper: An authoritative document that addresses a problem and presents a solution.
Wiki: A collaborative website or system where users can add and edit content.
WYSIWYG (What You See Is What You Get): An editing interface that displays content as it will appear when published.

X¶

XML (Extensible Markup Language): A markup language for encoding documents in a format readable by humans and machines.

Y¶

YAML (YAML Ain't Markup Language): A human-readable data format often used for configuration files and metadata.

Z¶

Zero state: The initial empty state of an application before the user has added data.

Contributing¶

This glossary is not exhaustive. If you encounter terms that should be added, consider contributing to the technical writing community by sharing definitions and explanations.