Documentation Taxonomy¶
This document defines the document types used across this repository, and across venture-level documentation that follows the same conventions. Every authoritative document should carry front matter that makes its type, status, and owner clear at a glance. If a reader cannot tell what kind of document they are looking at, or how binding it is, that is a defect in the document.
Why a taxonomy¶
Devonshire Digital and its ventures produce many kinds of written material: binding rules, recommended patterns, historical records, reusable starting points, and contractual specifications. Treating all of these the same way leads to two failure modes:
- Non-binding material (a guide, a template, an example) being treated as if it were mandatory.
- Binding material (a policy, an approved standard) being treated as optional or being silently reinterpreted.
The taxonomy below exists to prevent both. See authority-and-inheritance.md for how these types interact in a precedence order, and document-lifecycle.md for how a document moves through statuses.
Document types¶
Policy¶
A mandatory company (or venture) rule. Policies state what must or must not happen. Examples: information classification rules, security requirements, AI prohibited behaviors, evidence requirements for high-risk claims. Policies are the highest form of internally authored authority below explicit human instruction and legal/safety requirements. A policy is never casually overridden by a lower-tier document.
Standard¶
A required or strongly preferred pattern for doing something a particular way, so that outputs are consistent and interoperable. Examples: the document metadata standard, ADR formatting, the product specification format, workbook architecture conventions. Standards are binding once approved, but are narrower in scope than policy — they govern how something is done, not whether it is allowed.
Guide¶
Recommended steps or explanatory material intended to help a person or agent do something well. Guides are advisory. They may describe good practice, but deviating from a guide is not by itself a violation, provided the underlying policy and standards are still met.
Template¶
A reusable starting structure. A template is not itself policy, and content generated from a template does not inherit the template's authority — it must be evaluated on its own merits and, once filled in, may need its own front matter, review, and approval. Templates must be clearly identified as templates (see document-metadata-standard.md).
Record¶
A dated artifact describing what happened or what was decided. Examples: an Architecture Decision Record (ADR), a release record, a retrospective, a research record. Records are historical — they describe a point-in-time decision or event. They remain accurate as history even after the underlying decision is superseded; the record itself should not be edited to hide what was actually decided. Corrections happen via a new record or an explicit "superseded by" link.
Specification¶
A defined contract for a venture, product, feature, component, data model, or calculation. Specifications are binding on implementation: an implementation that contradicts an approved specification is a defect in the implementation, not license to reinterpret the specification. See authority-and-inheritance.md for how specifications rank against policy and standards.
Expectations for every document type¶
- Every authoritative document carries metadata (see
document-metadata-standard.md) identifying at minimum its
document_type,status, andowner. - Document type is not decorative. It determines how much weight the document carries in a conflict (see authority-and-inheritance.md) and what process is required to change it (see change-management.md).
- A document should not mix types. A guide that contains a few mandatory rules should either be split, or have those rules promoted into a policy/standard document that the guide then links to.