Glossary · 4 · Structure and semantics
Document-domain markup
Also known as: Document domain (structured writing), Document-domain structure
In structured writing as described by Mark Baker, document-domain markup is markup that records the structures of a document — such as sections, titles, lists, tables, procedures and steps — independently of how they will be formatted in any medium, but without recording what the content is about.
- Structured writing
- Markup
In one sentence
Document-domain markup records document structures such as sections, lists and steps, independent of formatting but not of the subject (Mark Baker).
Example
A step is tagged as a step inside a procedure and a warning as a note of type warning; the stylesheet decides fonts and icons, but the markup does not say which valve, which torque value or which hazard the text is about.
How it applies
- The domains: In Structured Writing: Rhetoric and Process (XML Press, 2018), Mark Baker introduces four domains of structured writing: media, document, subject and management. Media-domain markup records appearance (bold, a font size); document-domain markup records document structures that are common to many subjects and can be formatted in many ways — in his TechWhirl series he uses the list as the example of such a structure; subject-domain markup records the subject matter; management-domain markup supports processes such as reuse and conditional text.
- Typical vocabularies: Most general documentation vocabularies are largely document-domain: DITA topics and their elements, DocBook, HTML and Markdown headings and lists. Baker notes that DITA and DocBook can be extended into the subject domain; in DITA this happens through specialization.
- In documentation practice: Document-domain markup is what lets one source be published to PDF, HTML and help formats, and lets editors enforce a consistent document structure through a content model. It cannot check whether a procedure names every required parameter, because the parameters are not marked up as such.
Document-domain vs. subject-domain markup
Document-domain markup says “this is a step”; subject-domain markup says “this is the torque value for the flange bolts”. Moving content toward the subject domain lets software validate, sort and present it by its meaning and can factor out variation in document structures, at the cost of designing vocabularies for each subject.
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 Document Domain,” TechWhirl: https://techwhirl.com/structured-writing-in-the-document-domain/
- Mark Baker, “Structured Writing: Writing in the Media Domain,” TechWhirl: https://techwhirl.com/structured-writing-writing-in-the-media-domain/