diff --git a/docs/evidence/DOCS_ESCALATION_POLICY.md b/docs/evidence/DOCS_ESCALATION_POLICY.md new file mode 100644 index 00000000..4dd81f7c --- /dev/null +++ b/docs/evidence/DOCS_ESCALATION_POLICY.md @@ -0,0 +1,18 @@ +# Documentation Escalation Policy + +When a documentation issue cannot be resolved at the contributor level, it escalates. + +## Levels + +| Level | Who | Scope | Example | +|-------|-----|-------|---------| +| 1 | Contributor | Own changes | Fixing a typo | +| 2 | Reviewer | PR scope | Resolving a doc structure disagreement | +| 3 | Maintainer | Project scope | Policy change affecting all docs | +| 4 | Project lead | Cross-project | License or safety doc changes | + +## Rules + +- Escalate only after attempting resolution at the current level. +- Document the escalation in the PR or issue comments. +- Higher levels can delegate back to lower levels. diff --git a/docs/evidence/DOCS_EXCEPTION_POLICY.md b/docs/evidence/DOCS_EXCEPTION_POLICY.md new file mode 100644 index 00000000..90052b2d --- /dev/null +++ b/docs/evidence/DOCS_EXCEPTION_POLICY.md @@ -0,0 +1,19 @@ +# Documentation Exception Policy + +An exception allows a deliberate deviation from a documentation standard. + +## When to Use + +- A document must be published before all standards can be met. +- A legacy document cannot be updated without breaking external references. +- A temporary situation requires faster publishing than full compliance allows. + +## Requirements + +- The exception must be documented in the decision log. +- The exception must include a reason and an expiry date. +- The exception must be reviewed at expiry. + +## Related + +- `schemas/decision_log.schema.json` — decision log format diff --git a/docs/evidence/DOCS_MINOR_EDIT_POLICY.md b/docs/evidence/DOCS_MINOR_EDIT_POLICY.md new file mode 100644 index 00000000..78b98c92 --- /dev/null +++ b/docs/evidence/DOCS_MINOR_EDIT_POLICY.md @@ -0,0 +1,23 @@ +# Documentation Minor-Edit Policy + +Minor edits can be made without full review. + +## What Counts as Minor + +- Typo fixes +- Link corrections +- Formatting improvements (tables, lists, headings) +- Updating version numbers +- Clarifying wording without changing meaning + +## What Requires Full Review + +- Adding or removing sections +- Changing policy statements +- Adding or removing claims +- Restructuring documents + +## Process + +Minor edits can be committed directly to `main` or submitted as a PR with +the `minor` label. Review is optional but encouraged. diff --git a/docs/evidence/DOCS_RETIREMENT_POLICY.md b/docs/evidence/DOCS_RETIREMENT_POLICY.md new file mode 100644 index 00000000..c131c33e --- /dev/null +++ b/docs/evidence/DOCS_RETIREMENT_POLICY.md @@ -0,0 +1,24 @@ +# Documentation Retirement Policy + +Documents that are no longer accurate or useful should be retired, not +left to accumulate. + +## When to Retire + +- The document describes a process that no longer exists. +- The document has been superseded by a newer version. +- The document is inaccurate and cannot be fixed. +- The document has no identifiable audience. + +## Process + +1. Add a deprecation notice at the top of the document. +2. Update cross-references to point to the replacement. +3. After one review cycle, move the document to an archive directory. +4. After two review cycles, delete the document. + +## What Not to Retire + +- Evidence documents with historical benchmark results. +- Decision logs. +- Documents that are referenced by external publications. diff --git a/docs/evidence/DOCS_REVIEW_CADENCE_POLICY.md b/docs/evidence/DOCS_REVIEW_CADENCE_POLICY.md new file mode 100644 index 00000000..e90c80c7 --- /dev/null +++ b/docs/evidence/DOCS_REVIEW_CADENCE_POLICY.md @@ -0,0 +1,19 @@ +# Documentation Review Cadence Policy + +Documents are reviewed on a regular cadence to ensure freshness. + +## Cadence + +| Document Type | Review Cadence | Trigger | +|---------------|:--------------:|---------| +| Policy docs | Every 6 months | Calendar reminder | +| Getting-started guides | Every 3 months | Or after a CLI change | +| Evidence docs | Every 6 months | Or after a benchmark change | +| Concept cards | Annually | Or after a related policy change | +| Runbooks | Every 3 months | Or after a workflow change | + +## Process + +1. Reviewer checks accuracy, completeness, and link health. +2. Outdated docs are updated or flagged for retirement. +3. Review results are recorded in the decision log. diff --git a/tests/test_doc_policies.py b/tests/test_doc_policies.py new file mode 100644 index 00000000..4a6e29bc --- /dev/null +++ b/tests/test_doc_policies.py @@ -0,0 +1,21 @@ +"""Tests for documentation policy docs.""" +from pathlib import Path + +POLICIES = [ + "DOCS_EXCEPTION_POLICY.md", + "DOCS_ESCALATION_POLICY.md", + "DOCS_REVIEW_CADENCE_POLICY.md", + "DOCS_RETIREMENT_POLICY.md", + "DOCS_MINOR_EDIT_POLICY.md", +] + + +def test_all_exist(): + for p in POLICIES: + assert Path(f"docs/evidence/{p}").exists(), f"Missing: {p}" + + +def test_each_has_content(): + for p in POLICIES: + text = Path(f"docs/evidence/{p}").read_text() + assert len(text) > 100, f"{p} is too short"