Skip to content

Documentation Artifact Lifecycle

This document describes the stages a documentation artifact (a specification, standard, ADR, or similar substantive document) moves through, and where in the repository structure it typically lives at each stage. It is a structural companion to the status field defined in the metadata standard — see docs/governance/document-metadata-standard.md for the formal field definitions.

Stages

1. Idea

An unstructured or lightly structured note — a candidate product idea, a possible standard, a possible venture. No formal document yet exists. Typically lives in work/ as a working note, or as an entry in a venture's backlog file (e.g., ventures/<slug>/backlog.md, if that venture maintains one).

2. Draft (status: draft)

The idea has become a real document with the standard front matter, but is still being actively written or substantially revised. It is not yet considered ready for review. A candidate product's specification, for instance, moves from a backlog note into a directory based on the appropriate template (see templates/), typically inside the relevant venture's product area, once someone begins specification work in earnest.

3. Proposed (status: proposed)

The document is considered complete enough to be reviewed by its owner (a role, not a person). ADRs in this repository's founding session are recorded at proposed status because they represent decisions made during initial setup that have not yet passed a formal human review checkpoint. A proposed document stays in its normal location (e.g., docs/decisions/, docs/standards/, a venture's product directory) — proposal is a status change, not a relocation.

4. Approved / Rejected

  • Approved: the document's owner has formally reviewed and adopted it. Only a human can move a document to approved — see docs/company/responsible-ai-principles.md. No document in this repository carries approved status at the time of writing; the repository is in its initial founding/drafting phase.
  • Rejected: the owner reviewed the proposal and declined to adopt it. A rejected document is not deleted; it is retained with a note explaining the rejection (or moved to work/archive/ if it never reached durable value), so the reasoning is not lost.

5. Maintained

An approved document is periodically reviewed per its review_cycle field and kept current. Maintenance may produce a new version (version field increment) without changing its lifecycle stage.

6. Deprecated / Superseded

  • Deprecated: the document is no longer current guidance but is retained for historical reference (e.g., a decision that no longer applies but explains past reasoning).
  • Superseded: the document has been explicitly replaced by a newer one. The old document's status is updated and it typically gains a note pointing to the replacement; the new document's supersedes field points back to it. See docs/standards/archival-and-retention-standard.md for the mechanics — documents are never silently deleted.

Worked example: a candidate product

  1. Someone notes a possible new Digital Products workbook idea in a venture backlog file under ventures/digital-products/. (Idea)
  2. The idea is judged worth specifying. A new directory is created from templates/ (or a Digital Products-specific product template) and a specification document is started with status: draft. (Draft)
  3. The specification is filled out against the baseline in docs/standards/product-specification-standard.md and marked status: proposed for owner review. (Proposed)
  4. The venture or company owner reviews and formally adopts it, setting status: approved and an effective_date. (Approved)
  5. The specification is revisited on its review_cycle and updated as the product evolves. (Maintained)
  6. If the product is discontinued or the specification is replaced by a new version, the old specification is marked deprecated or superseded and retained rather than deleted. (Deprecated/Superseded)

Registry note

Machine-readable registries in portfolio/ may track a simplified version of this lifecycle (e.g., a lifecycle_status field on a product entry) for indexing purposes. The registries are a queryable index of state; the Markdown documents remain the authoritative record of why a document is at a given stage. See registry-architecture.md.

Report an issue about this page