From 089d3fb69b7cd4be320865d97543537646c8c39d Mon Sep 17 00:00:00 2001 From: OpenCode Date: Tue, 7 Jul 2026 13:25:16 +0700 Subject: [PATCH] Add 5 metric/documentation health docs Closes #659, Closes #660, Closes #661, Closes #662, Closes #653 - Release readiness, navigation health, maintenance health, contributor docs metric guides, health metric definitions --- .../DOCS_HEALTH_METRIC_DEFINITIONS.md | 19 +++++++++++++++++ .../evidence/METRIC_GUIDE_CONTRIBUTOR_DOCS.md | 16 ++++++++++++++ .../METRIC_GUIDE_MAINTENANCE_HEALTH.md | 11 ++++++++++ .../METRIC_GUIDE_NAVIGATION_HEALTH.md | 11 ++++++++++ .../METRIC_GUIDE_RELEASE_READINESS.md | 15 +++++++++++++ tests/test_metric_docs_batch.py | 21 +++++++++++++++++++ 6 files changed, 93 insertions(+) create mode 100644 docs/evidence/DOCS_HEALTH_METRIC_DEFINITIONS.md create mode 100644 docs/evidence/METRIC_GUIDE_CONTRIBUTOR_DOCS.md create mode 100644 docs/evidence/METRIC_GUIDE_MAINTENANCE_HEALTH.md create mode 100644 docs/evidence/METRIC_GUIDE_NAVIGATION_HEALTH.md create mode 100644 docs/evidence/METRIC_GUIDE_RELEASE_READINESS.md create mode 100644 tests/test_metric_docs_batch.py diff --git a/docs/evidence/DOCS_HEALTH_METRIC_DEFINITIONS.md b/docs/evidence/DOCS_HEALTH_METRIC_DEFINITIONS.md new file mode 100644 index 00000000..9c91b21a --- /dev/null +++ b/docs/evidence/DOCS_HEALTH_METRIC_DEFINITIONS.md @@ -0,0 +1,19 @@ +# Documentation Health Metric Definitions + +This document defines the core metrics used to assess documentation health. + +## Metric Definitions + +| Metric | Definition | Collection Method | Target | +|--------|------------|-------------------|--------| +| Link health | % of internal doc links that resolve | `check_doc_links.py` | 100% | +| Claim safety | Number of overclaiming phrases | `check_claims.py` | 0 | +| Index coverage | % of docs linked from PROJECT_INDEX.md | Manual audit | 100% | +| Freshness | Age since last significant update | `git log` | < 6 months | +| Onboarding time | Time from clone to demo | Stopwatch | < 15 min | +| Concept card coverage | % of artifact types with cards | Manual audit | 100% | + +## Related + +- `docs/evidence/DOCS_READINESS_CHECKLIST.md` — per-release checklist +- `docs/evidence/DOCS_REVIEW_CADENCE_POLICY.md` — review schedule diff --git a/docs/evidence/METRIC_GUIDE_CONTRIBUTOR_DOCS.md b/docs/evidence/METRIC_GUIDE_CONTRIBUTOR_DOCS.md new file mode 100644 index 00000000..13204fd2 --- /dev/null +++ b/docs/evidence/METRIC_GUIDE_CONTRIBUTOR_DOCS.md @@ -0,0 +1,16 @@ +# Metric Guide: Contributor Docs + +**Question:** Does a new contributor have everything they need to make a first change? + +**What to track:** Whether all contributor-facing docs cover the full path from setup to merged PR. + +**Documents to check:** +- CONTRIBUTING.md +- QUICKSTART.md +- CONTRIBUTOR_CURRICULUM.md +- RUNBOOK_PICKING_UP_ISSUE.md +- RUNBOOK_ASKING_FOR_REVIEW.md + +**Target:** A contributor can follow the documented path without gaps. + +**What good looks like:** A first-time contributor can clone, run the demo, pick an issue, make a change, and submit a PR using only the documented steps. diff --git a/docs/evidence/METRIC_GUIDE_MAINTENANCE_HEALTH.md b/docs/evidence/METRIC_GUIDE_MAINTENANCE_HEALTH.md new file mode 100644 index 00000000..0fe0d5fa --- /dev/null +++ b/docs/evidence/METRIC_GUIDE_MAINTENANCE_HEALTH.md @@ -0,0 +1,11 @@ +# Metric Guide: Maintenance Health + +**Question:** Are the docs staying current, or are they accumulating stale content? + +**What to track:** Age of last significant update per document. + +**Target:** No document older than 6 months without review. + +**How to measure:** Check `git log --oneline docs/` for each document. + +**What good looks like:** Active documents are updated within the last 3 months. Stale documents are flagged for review or retirement. diff --git a/docs/evidence/METRIC_GUIDE_NAVIGATION_HEALTH.md b/docs/evidence/METRIC_GUIDE_NAVIGATION_HEALTH.md new file mode 100644 index 00000000..19c742c3 --- /dev/null +++ b/docs/evidence/METRIC_GUIDE_NAVIGATION_HEALTH.md @@ -0,0 +1,11 @@ +# Metric Guide: Navigation Health + +**Question:** Can a reader find the document they need without searching? + +**What to track:** Whether all docs are linked from PROJECT_INDEX.md. + +**Target:** 100% of documents in docs/ are indexed in PROJECT_INDEX.md. + +**How to measure:** Compare `find docs/ -name "*.md"` against links in PROJECT_INDEX.md. + +**What good looks like:** A new reader can navigate from PROJECT_INDEX.md to any document in one or two clicks. diff --git a/docs/evidence/METRIC_GUIDE_RELEASE_READINESS.md b/docs/evidence/METRIC_GUIDE_RELEASE_READINESS.md new file mode 100644 index 00000000..13fb19c5 --- /dev/null +++ b/docs/evidence/METRIC_GUIDE_RELEASE_READINESS.md @@ -0,0 +1,15 @@ +# Metric Guide: Release Readiness + +**Question:** Is the project ready for a public release? + +**What to track:** Whether all release artifacts exist and pass checks. + +**Artifacts to check:** +- `make full-reproducibility-report` succeeds +- `python scripts/check_doc_links.py` reports 0 broken links +- `python scripts/safety/check_claims.py` — no overclaiming language +- `docs/review/PUBLICATION_PACK.md` checklist is complete + +**Target:** All checks pass. + +**What good looks like:** A maintainer can run `make full-reproducibility-report`, review the output, and decide whether to proceed. diff --git a/tests/test_metric_docs_batch.py b/tests/test_metric_docs_batch.py new file mode 100644 index 00000000..edda0462 --- /dev/null +++ b/tests/test_metric_docs_batch.py @@ -0,0 +1,21 @@ +"""Tests for metric docs batch.""" +from pathlib import Path + +FILES = [ + "METRIC_GUIDE_RELEASE_READINESS.md", + "METRIC_GUIDE_NAVIGATION_HEALTH.md", + "METRIC_GUIDE_MAINTENANCE_HEALTH.md", + "METRIC_GUIDE_CONTRIBUTOR_DOCS.md", + "DOCS_HEALTH_METRIC_DEFINITIONS.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path(f"docs/evidence/{f}").exists(), f"Missing: {f}" + + +def test_each_has_content(): + for f in FILES: + text = Path(f"docs/evidence/{f}").read_text() + assert len(text) > 100, f"{f} too short"