Skip to content

Document Metadata Standard

Every substantive document in this repository (and in venture-level documentation that follows company conventions) uses the YAML front matter defined here. Simple index files (a README.md that only lists and links other files) may use a lighter version — see Lightweight front matter below.

Standard front matter

---
title: Example Document
document_id: DD-EXAMPLE-001
document_type: policy|standard|guide|template|record|specification
status: draft|proposed
owner: Founder|Repository Maintainer
applies_to:
  - company
version: 0.1.0
effective_date:
last_reviewed:
review_cycle: annual
supersedes:
related_documents:
  - path/to/other.md
---

Field definitions

title

Human-readable document title. Should match the first # heading in the document body.

document_id

A stable, unique identifier, prefixed DD- followed by a category segment and a zero-padded number, e.g. DD-GOV-001, DD-AI-001, DD-SHELFERY-014. Rules:

  • IDs are assigned once and never reused for a different document.
  • IDs are never renumbered later, even if documents are reorganized, renamed, or the numbering looks out of order. Renumbering breaks external references and historical records.
  • IDs are never dates or timestamps. Use version, effective_date, and last_reviewed for time information.
  • Category segments are short and stable (e.g. GOV for governance, AI for AI instructions, SHELFERY / DP for venture-specific documents). New categories may be introduced as needed.

document_type

One of the types defined in documentation-taxonomy.md:

  • policy — mandatory company or venture rule.
  • standard — required or strongly preferred pattern.
  • guide — recommended, advisory material.
  • template — reusable starting structure, not itself binding.
  • record — dated artifact of what happened or was decided.
  • specification — defined contract for a venture/product/feature/component/data model/calculation.

status

  • draft — actively being written or revised. Not yet reviewed for accuracy or completeness. Not to be treated as authoritative guidance for anything beyond "this is the current thinking."
  • proposed — complete and believed correct, submitted for human review and approval. Not yet binding.
  • approved — reviewed and formally accepted as current, binding guidance by the human authority with rights to do so (see decision-rights.md). No document in this repository should be marked approved without explicit human approval. An AI agent must never set a document's status to approved.
  • deprecated — no longer recommended, but not yet replaced by a specific successor. May still be referenced for historical understanding.
  • superseded — explicitly replaced by another, named document (recorded in supersedes on the successor document, and ideally cross-referenced from the superseded document itself).

Newly authored content in this repository starts as draft or proposed. As a rule for the current phase of this repository, nothing should be marked approved — that step requires a deliberate human decision made outside of routine agent-driven content generation.

owner

A role, not a personal name: e.g. Founder, Repository Maintainer, Venture Lead, Product Owner, Security and Privacy Reviewer. See decision-rights.md for the full role list. Using roles instead of names keeps documents accurate as people's responsibilities change, and matches this repository's role-based ownership model.

applies_to

A list of scopes the document governs. Valid values:

  • company — applies to Devonshire Digital LLC as a whole and, by inheritance, to all ventures (see authority-and-inheritance.md).
  • A venture slug, e.g. shelfery, digital-products — applies to that venture specifically.

A document may list multiple values if it applies to more than one scope.

version

A semver-like version for the document itself. See versioning-and-release-management.md for the rules on when to bump major/minor/patch.

effective_date

The date the document (at its current version) takes effect. Left blank while the document is still draft or proposed.

last_reviewed

The date of the most recent review. Used together with review_cycle to flag documents that are due for a look.

review_cycle

How often the document should be revisited, e.g. annual, quarterly. See document-lifecycle.md.

supersedes

The document_id of a document this one replaces, if any. Leave blank otherwise.

A list of relative paths to related documents, for cross-navigation. Not a substitute for inline links in the body text.

Rules

  1. Draft and proposed content is expected. Most content in a young repository will legitimately be draft or proposed. That is fine and should be stated plainly rather than hidden.
  2. Never mark a policy approved without explicit human approval. This applies to any document, but is called out specifically for policy and standard types given their binding nature.
  3. Templates must be identified as templates. Set document_type: template. Do not let a template's example content read as if it were itself an approved instance.
  4. Examples must not look authoritative. Example content embedded inside a guide or template (sample data, sample specs, sample claims) must be visually and textually distinguishable from real, approved content — label it "Example" and avoid realistic-looking identifiers, financial figures, or customer data that could be mistaken for real records.
  5. Do not scatter untracked TBD statements through documents. If something is genuinely unresolved, record it as an entry in assumptions-register.md (if it's a working assumption standing in for a decision) or open-questions.md (if it's a question awaiting a decision), and link to that entry from the document instead of leaving a bare "TBD" with no trace of ownership or follow-up.
  6. Use stable document IDs; never reuse or renumber them. See the document_id rules above.

Lightweight front matter for index files

A simple README.md that exists only to index and link other documents in its directory may use a reduced form:

---
title: Governance Documentation Index
document_type: guide
status: draft
owner: Repository Maintainer
applies_to:
  - company
---

Index files still declare document_type, status, and owner so their role is unambiguous, but may omit document_id, version, effective_date, last_reviewed, review_cycle, supersedes, and related_documents where those fields would add no value.

Report an issue about this page