Explainer
Metadata for Technical Publications
The Short Answer
Data a System Can Act On
Metadata is data about a unit of content, held in a form software can read. For a general documentation site that usually means tags for search. For an aircraft or defense library it carries more weight: the same fields decide which configuration a maintainer sees, whether a module may be sent to a given recipient, and whether you can show an auditor how a page came to read as it does.
Five groups of fields cover most of what such a library needs. Each is described below, followed by where the two main structured formats keep them. For the short definition, see the glossary entries for metadata and taxonomy.
What a Library Needs
Five Groups of Fields
- Identity
- What this unit of content is, which language it is in, and which issue of it you are holding. Without a stable identifier nothing else can point at it, and a revision cannot be told from the original.
- Applicability
- Which products, serial ranges, modifications, or configurations the content is true for. This is the field that decides whether a maintainer sees the right step.
- Status and revision
- Who owns it, when it was issued, why it changed, and how far it has been checked. A reviewer or auditor reads this to learn whether content is draft, verified, or superseded.
- Security and export markings
- Classification, distribution statement, export control, and handling and destruction instructions. These decide who may receive the content, so a delivery system has to be able to read them.
- Audience
- The role, skill level, or task the content is written for. It lets a portal show a technician the procedure and an engineer the theory.
Notice what is missing: keywords. Search tags matter, but they are the easiest group to add later. The five above are the ones that are expensive to retrofit, because they describe facts about the content that someone has to have recorded at the time.
In S1000D
The Identification and Status Section
In S1000D, nearly all of this sits in one place at the top of every data module, the identification and status section. The element names below come from the Issue 4.2 schema; later issues may add or rename elements, so check the issue your program uses.
- Identity: dmIdent and dmAddressItems
- The data module address holds the data module code, the language, and the issue information, plus the issue date and title. The code is the identifier every reference points at.
- Applicability: applic or applicRef
- The status block requires one of the two, so every module declares what it applies to, even if the answer is everything. Finer applicability can sit on individual steps and warnings.
- Status: responsiblePartnerCompany, originator, qualityAssurance, reasonForUpdate
- Who is responsible, who originated it, whether it is unverified or has had a first and optional second verification, and why this issue exists.
- Security: security and dataRestrictions
- A security classification is required on every module. Optional restriction instructions carry data distribution (required inside that block), export control, data handling, data destruction, and data disclosure.
- Audience: skillLevel, plus the information code
- A skill level can be recorded per module. What the module is for (procedure, description, fault isolation) is carried by its information code.
Two points deserve emphasis. The status block makes applicability and security mandatory rather than optional, which is why S1000D libraries are easier to audit than page-based ones. And the permitted values are mostly not in the schema at all: a project's business rules, enforced by a BREX, decide them. Read the data module code for the identity field and S1000D applicability for the configuration tables behind the applicability field.
In DITA
Prolog, Attributes, and Subject Schemes
- Identity and lifecycle: the prolog
- Elements such as author, publisher, source, copyright, resourceid, and critdates (created and revised dates) record origin and dates. The specification notes that the prolog is mostly not displayed and is used by indexing and navigation processes.
- Audience and product: the metadata element
- audience records the type, job, and experience level; prodinfo records product name, version, release, platform, and program number. The specification says these let computational processes select topics, build search indexes, or customize navigation.
- Applicability: profiling attributes
- @props, @product, @platform, @audience, and @otherprops sit on any element, down to a single step or list item, and take space-delimited values. A DITAVAL file then includes, excludes, or flags content by attribute and value at build time.
- Controlled vocabulary: subject scheme maps
- A subject scheme map defines the allowed values for an attribute and can nest them as a hierarchy. Processors are expected to warn when a value is not in the scheme, which is what keeps a tag set from drifting.
- Access: permissions and data
- permissions has a @view attribute whose values a program can define. Nothing in the base prolog is named for distribution statements or export control, so those markings go in permissions values, data elements, or a specialization the team designs.
The split is the useful thing to remember. S1000D puts the fields in a fixed block with a fixed order and lets business rules fill in values. DITA offers a looser vocabulary and expects the team to decide which fields exist, then enforce the values with a subject scheme. Neither is better; the DITA route asks for more design work up front. Our comparison of S1000D and DITA and the guide to maps, keys, and filtering go further.
What It Drives
Filtering, Search, Delivery, Audit
- Filtering
- A viewer or build reads applicability and returns only the content true for one tail number or variant. The wrong-variant page is never rendered.
- Search
- Product, audience, and information type narrow results before a user types a word, and controlled values stop three spellings of one system splitting the index.
- Delivery
- Security and distribution fields decide which packages go to which recipient. A delivery that cannot read them relies on someone remembering.
- Audit
- Issue, date, reason for update, and verification status let you show what changed, who approved it, and what a technician had on a given day.
Two existing explainers show the stakes. A distribution statement is a permission-scoping field, covered in DoD distribution statements A to F; export-controlled technical data is covered in ITAR technical data. And for history, revision control and effective-dated publishing both depend on the status fields being right.
Metadata also decides how well software can answer from your library. A model or search index grounded on content with no applicability or status will mix configurations and superseded text; see AI answers from your documents.
Getting It Right
Design the Scheme Before You Author
- List the questions the library must answer: which variant, which issue, who may receive it, who checked it.
- Map each question to one field and one owner. A field nobody is responsible for will be wrong within a year.
- Fix the allowed values in one place (business rules or a subject scheme) and validate against them. See managing defined terms.
- Keep the applicability vocabulary small, and feed it from configuration records you trust.
- Check that your CSDB or CCMS can read and filter on each field, because a field that cannot be queried is only documentation. CCMS requirements lists what to ask for.
FAQ
Questions We Hear
What is the difference between metadata and taxonomy?
Metadata is the set of fields attached to a unit of content. A taxonomy is the controlled list of values those fields may take, such as the allowed product names. In DITA a subject scheme map is the standard way to define that list; in S1000D the business rules and the cross-reference tables do the job.
Does DITA have a built-in way to mark export-controlled content?
Not as a dedicated element in the base prolog we checked in DITA 1.3. The permissions element and the data element are the nearest places, and a team can specialize its own. Define the marking vocabulary in a subject scheme so every author uses the same values.
Is S1000D metadata optional?
Much of it is not. In the Issue 4.2 schema every data module's status block needs a security classification, a responsible partner company, an originator, a BREX reference, a quality assurance entry, and either an applicability statement or a reference to one. What the values mean is set by the project's business rules.
Who should own the metadata scheme?
One named owner per program, with the scheme settled before authoring starts. Fields added later have to be back-filled across the whole library, and a field filled in inconsistently is worse than no field because people trust it.
Does a distribution statement count as metadata?
Yes. It is a marking that travels with the content and controls who may receive it, which is exactly the job of metadata. Our explainer on DoD distribution statements covers what each letter means; this page covers where to store it.
Get In Touch
Settle the Fields Before You Author
Tell us about your library and the configurations, markings, and recipients it has to support. We will tell you which fields it needs and where they should live.