DITA Migration Glossary: Terms You Will Meet

This DITA migration glossary defines the terms a documentation team meets when it moves legacy content into DITA: ditabase, root map, bookmap, key map, conref, keyref, ditaval, specialization and the rest. Each definition is the working one our conversion guides use, and each names the guide where the term decides something.

The standard and its building blocks

DITA

The OASIS open standard for topic-based technical content. Its reason to exist is single-sourcing: reuse through conref and keyref, conditional publishing with ditaval profiling, and output to many channels. The case for and against it is in why migrate to DITA.

Topic

The working unit of single-sourcing. Check-in, reuse, review and version history all operate on individual topics.

Topic type (infotype)

The kind of topic: concept, task, reference or glossentry. Good typing rules are mechanical: a body whose spine is an ordered list is nearly always a task, and a parameter table is a reference.

DTD

The grammar that DITA content is validated against. DITA has published DTDs, and a CCMS enforces one on import: the standard grammar, or your own.

Specialization

Your organisation's own form of the DITA model, carried in your DTD: its element rules, its topic types and its required elements. A house specialization may forbid a plain topic and require every file to be a concept, task or reference. "Valid DITA" and "valid against your DITA" are therefore different claims.

Prolog

The part of a topic that carries its metadata: keywords, index terms, audience, product, component, lifecycle status. A CCMS indexes on prolog elements, so content with empty prologs imports cleanly and is then invisible to search and filters. Knowledge Fabric writes discovered keywords into topic prologs.

CALS table

The table form that conversions to DITA produce. A CALS table can validate against the DTD and still be arithmetically impossible: a span overrunning the declared columns, two cells claiming the same position, a morerows value running off the end of its section.

DITA Open Toolkit (DITA-OT)

The open toolchain that publishes DITA to multiple channels. The DITA migration checklist asks you to decide before conversion whether the content will live in a CCMS, or in Git with the DITA Open Toolkit.

Lightweight DITA route

The route by which our Markdown to DITA conversion reads Markdown: the standard interpretation that the official DITA toolchain applies, not a home-grown reader.

Maps, keys and file shapes

DITA map and bookmap

The file that holds a publication together. It keeps the topics in reading order and governs a repository of individual topics. Whether the target is a map or a bookmap is decided before conversion starts.

Root map

A map that no other map references: the top of a publication's hierarchy. The DITA topics to composite conversion treats each root map as one publication and expands its nested submaps in the order a reader would meet them.

Key map

The map that defines the keys of a publication, so that key-based references have somewhere to resolve. A split of composite DITA generates one across the new topic set.

Key space and key scope

A key space is the set of key definitions that a publication resolves its keys against; a key scope is a part of a map that has a key space of its own. The same key can legitimately mean two different things under two different maps, so keys are resolved in each publication's own key space. Keys that collide across publications are a common cause of failed imports.

Composite DITA (ditabase)

A single composite file that holds many topics inside one document. It is valid DITA and convenient for a reviewer, translator or archivist, but it gives per-topic check-in and reuse nothing to hold on to. Splitting one is covered in composite DITA to topics.

Topic-per-file (split DITA)

One topic per file, each a unit of its own. Most CCMS and single-sourcing workflows require this form. The reverse move produces one self-contained composite file per publication.

Reuse and conditions

Single-sourcing

Authoring content once in DITA and generating every output you need as outputs you regenerate, not as copies you maintain.

Conref

Reuse by content reference. One master block is stored and referenced wherever it is needed, so a single edit propagates automatically. Copy-paste reuse duplicates the text instead.

Keyref

Reuse or linking through a key. The content names a key, and the key map of the publication says what that key stands for. Legacy variables can survive a migration as keys, managed centrally, instead of being flattened into their values.

Profiling and ditaval

How DITA carries conditional text. Content is marked with profiling attributes, and a ditaval filters on them at publish time. Conditional text that is flattened into plain paragraphs still validates, and the single-sourcing is gone.

Content Convergence

Our name for reuse and normalisation after conversion: duplicate topics, images and repeated blocks are collapsed to one master and every reference is rewritten to point at it.

Validation and delivery

CCMS

A component content management system: the platform the migrated DITA is imported into and authored in. Its check-in and check-out, versioning, review, translation and reuse management all operate on topics as individual units.

Import gate

Everything between "valid DITA delivered" and "content accepted in the CCMS": the schema the platform enforces, map and folder structure, ID and filename conventions, conref and keyref integrity, assets and metadata. It fails late, in bulk and usually silently. See CCMS migration.

Completeness check

Validation of a whole repository in one run: well-formedness, DTD conformance, links, cross-references, conref, keyref, image references, duplicate IDs and keys, circular maps and table grids. The DITA completeness check guide lists every check.

Content conservation

The rule that text is never dropped. Structure may degrade gracefully where it cannot be determined, and the result is flagged for review; the words survive.

Orphan

A topic or file that exists but that no navigation or map references. Orphans should be converted and flagged for a decision, not silently excluded.

Project terms

Conversion, migration, transformation

DITA conversion turns content authored in another format into DITA. DITA migration moves a whole body of legacy documentation into DITA inside your CCMS, run as a project. DITA transformation is the work done with content once it is already in DITA. See also: DITA conversion vs DITA migration.

Generic run and customer-specific run

A generic run gives valid, well-formed DITA with inferred structure, generic topic types, generated IDs and the source's own style names. A customer-specific run maps your styles to semantic elements, converts conditions to your profiling scheme, follows your reuse strategy and naming, and validates against your own DTD.

Style-to-element map

The list of every paragraph and character style actually in use, with the DITA element and attributes each one becomes: a "Caution" style becomes a caution note. Step 8 of the DITA migration checklist calls it the highest-value artefact in the project.

Pilot

A representative slice converted first and reviewed with you, where the mapping, the topic types and the ID and folder conventions are agreed.

The second pile

The legacy nobody can scope: scanned page images, PDFs with no styling information, print-era manuals. It converts on a different path from tool-managed content, and it is the subject of the second pile and of our guide to legacy content migration.

See the terms in your own output

The free 25-page sample returns your own pages as topics, a DITA map, metadata and a validation report.

Related guides

Send us 25 pages. The messier, the better.

We'll convert them to DITA free of charge — through the real pipeline, not a demo — and review the output with you. Then we'll discuss pricing one-to-one.

Get your free 25-page sample