Glossary
Reference
Definitions of technical-writing and structured-authoring terms used throughout this manual, each linked to the article that covers it in depth.
Overview
Section titled “Overview”Quick definitions for terms used across this manual. Each entry links to the article that covers the concept in depth - this page is for lookup, not for learning a topic from scratch.
- Branch
- A parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time. See using branches in source management systems.
- CI/CD (continuous integration and continuous delivery)
- Automation that checks every change as soon as it is submitted (continuous integration) and publishes the result once the checks pass (continuous delivery). In docs-as-code, a CI/CD pipeline builds the documentation, runs tests such as link and schema checks, and deploys the site. See a practical CI/CD pipeline for documentation.
- CMS (Content Management System)
- A tool that adds workflow and file-locking to content management, at the cost of reliability trade-offs compared to plain version control. See CMS: workflow as a bonus, but reliability to be tested.
- Commit
- A recorded snapshot of changes in a Git repository, with an author, a date, and a message explaining the change. Commits form the project history that branches start from and that reviewers and translators compare. See Git: from file to content.
- Concept, task, reference
- DITA XML’s three base information types: a concept introduces or explains an idea, a task is a numbered procedure, and a reference is lookup material like a parameter list. This manual’s own articles are tagged with the same three types. See structured and unstructured formats.
- Conditional text
- Content marked as applying only to a given audience, product version, or output, so that one source can be filtered at build time into different deliverables. DITA XML implements it with ditaval files; template engines such as Jinja do the same for text formats. See create different documents from the same sources using Jinja.
- Conref
- A DITA XML mechanism for reusing a block of content by reference: the content of a target node is replaced by the content of a source node at compile time. See reusing information blocks with conrefs.
- Content reuse
- Writing a piece of information once and using it in several places or deliverables instead of copying it, so that a correction made once applies everywhere. Conrefs, conditional text, and single-sourcing are ways to achieve it. See case study: NuFirewall documentation.
- DITA-OT (DITA Open Toolkit)
- The open-source publishing engine that transforms DITA XML sources, assembled by a ditamap, into target formats such as PDF (via XSL-FO) and HTML. See DITA XML and XSL-FO tutorials.
- Ditamap
- An external table-of-contents file that assembles DITA XML topics into a document, without the topics themselves needing to know their position in that document. See on-demand DITA content assembly with ditamaps.
- Ditaval
- A DITA XML filter file that includes or excludes content marked with matching attributes at compile time - the mechanism behind DITA’s conditional text. See provide targeted information with ditaval conditional text.
- DocBook
- A semantic XML markup language for technical documentation, organized in books, chapters, and sections rather than typed topics. It predates DITA XML and is the usual point of comparison when choosing a structured format. See from document to modular document base.
- Docs-as-code
- Treating documentation like source code: text-based formats, version control, code review, and CI/CD, rather than a separate publishing process. See adopt docs-as-code.
- DITA XML
- A structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps. See structured DITA XML format.
- DTD (Document Type Definition)
- The oldest XML schema language: it declares which elements and attributes a document may contain, and in what order. DITA XML is distributed with DTDs as well as XSD schemas.
- Information typing
- The discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose. See structured and unstructured formats.
- llms.txt
- A plain-text file at the root of this site (
/llms.txt) that follows the llms.txt convention: a concise table of contents pointing programs and AI agents to the machine-readable versions of this manual (per-page Markdown, JSON indexes, and full-corpus files). See about this manual’s API. - Machine-readable documentation
- Documentation published in a form that programs can consume directly, such as Markdown files, JSON indexes, or plain-text corpora, alongside the HTML pages rendered for human readers. This manual generates both from the same sources at build time. See about this manual’s API.
- Markdown
- A lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading
#for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant. See choose an authoring model. - Minimalism (minimalist writing)
- A task section contains only what’s needed to complete the task - prerequisites, steps, and a few closely related elements - with conceptual and reference material placed elsewhere. See structured and unstructured formats.
- Modular documentation
- Content built from small, reusable, standalone units (topics or modules) assembled on demand, rather than authored as monolithic documents. See from document to modular document base.
- OpenAPI
- A standard, machine-readable format (YAML or JSON) for describing an HTTP API: its endpoints, parameters, request and response schemas, and status codes. Reference documentation can be generated from it, leaving writers to add the usage guidance the description can’t carry. See template: API documentation.
- Pull request
- A request to merge a branch’s changes into the main line, presented as a reviewable set of differences: reviewers comment, automated checks run, and approval is recorded before publication. GitLab calls it a merge request. See content creation.
- Repository
- The place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file. See repository.
- reStructuredText
- A plain-text markup language from the Python ecosystem, richer than Markdown (directives, roles, cross-references), and the native source format of the Sphinx documentation generator. See automatically insert data into a reStructuredText file.
- Schema
- A formal description of the structure a document or data file must follow: which elements or fields are allowed, in what order, and with which values. Validating content against a schema (DTD, XSD, or RELAX NG for XML; JSON Schema for JSON) catches structural errors before publication. See structured and unstructured formats.
- Single-sourcing
- Generating multiple deliverables (PDF, HTML, help formats) from one source, rather than maintaining a separate source per output format. See target format.
- Source format
- The format content is authored in, as distinct from the target format it’s published to - the recipe versus the dish. See source format.
- Writing content whose markup encodes meaning (this is a warning, this is a step) rather than just visual appearance - enabling automated processing, reuse, and consistency checks that unstructured formats can’t support. See structured and unstructured formats.
- Target format
- The format a reader actually consumes - PDF, HTML, compiled help - generated from the source format. See target format.
- Technical communication
- The broader discipline that spans the entire product life cycle and reaches general audiences, prospects, and journalists - as distinct from technical writing, which produces user-facing product documentation after a sale. See from technical writing to technical communication.
- Topic
- The smallest autonomous, titled unit of information in DITA XML, typed as concept, task, or reference and assembled into documents via ditamaps. See topics: basic DITA XML information modules.
- Version control
- Recording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code. See version management systems.
- WYSIWYG
- Short for what you see is what you get: editing in a view that looks like the final page, as in a word processor, with layout applied by hand. Its opposite is structured authoring, where writers mark up meaning and layout is applied automatically at publication. See source format.
- XSD (XML Schema Definition)
- The W3C schema language for XML, itself written in XML. DITA XML’s XSD schemas define which elements each topic type allows; a file that breaks them fails validation, which also constrains what conrefs and conditional text may produce. See case study: NuFirewall documentation.
- XSL-FO
- A stylesheet language for transforming and laying out XML content for print/PDF output, commonly paired with DITA XML publishing pipelines. See DITA XML and XSL-FO tutorials.
- XSLT (XSL Transformations)
- A language for transforming XML documents into other XML, HTML, or text documents. XML publishing chains such as the DITA Open Toolkit use XSLT stylesheets to produce HTML, or XSL-FO for PDF output. See source format.