Glossary · 4 · Structure and semantics
Subject-domain markup
Also known as: Subject domain (structured writing), Subject-domain structure
In structured writing as described by Mark Baker, subject-domain markup is markup that records the subject matter of the content — for a recipe, its ingredients, quantities and preparation time; for a machine, its parameters, components or error codes — rather than the document structures or the formatting in which the content will be presented.
- Structured writing
- Markup
- Semantics
In one sentence
Subject-domain markup records the subject matter itself, such as ingredients or error codes, rather than document structure or formatting (Mark Baker).
Example
An error message entry is written with fields for the error code, the message text, the cause, the affected station and the remedy; a publishing step turns these fields into a troubleshooting table in the manual and into the help text on the HMI.
How it applies
- The domains: Mark Baker’s Structured Writing: Rhetoric and Process (XML Press, 2018) distinguishes the media, document, subject and management domains of structured writing. In his TechWhirl article on the subject domain he uses the recipe as the example: a recipe can be written in the document domain as a heading, paragraphs and a numbered list, but a recipe document type records its introduction, ingredients and preparation as such and can impose and record the constraints of a recipe.
- Benefits: Subject-domain markup lets software validate content against the subject (every error code has a remedy), sort and present it in different ways, and generate document-domain output for several media. Baker argues that it also future-proofs content, because it records statements about the subject matter itself rather than about one presentation.
- Implementation: Subject-domain structures are either purpose-built vocabularies or extensions of general vocabularies — for example DITA specialization. Baker developed the lightweight markup syntax SAM for subject-domain writing. Industry data models for parameters, error messages or spare parts are subject-domain structures too.
- Machinery documentation: Parameter lists, error message catalogs, maintenance intervals and safety data are typical candidates, because the same subject data feeds manuals, HMIs, service portals and the information model of a product. Subject-domain markup records what the author enters; it does not verify that the data is correct.
Subject-domain vs. document-domain markup
Document-domain markup names generic document structures — sections, lists, steps — that occur in any subject. Subject-domain markup names the things the content is about. Content written in the subject domain is transformed into the document and media domains for publishing; the reverse is not possible without adding information.
External references
- Mark Baker, Structured Writing: Rhetoric and Process (XML Press, 2018), publisher page: https://xmlpress.net/publications/structured-writing/
- Mark Baker, “Structured Writing: Writing in the Subject Domain,” TechWhirl: https://techwhirl.com/structured-writing-writing-in-the-subject-domain/