From 98d902a784f8f8a2df2db60a29aadfc1a7115d97 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 14:34:43 +0700 Subject: [PATCH] Add 10 documentation standards and policies Closes #553, Closes #554, Closes #555, Closes #556, Closes #557, Closes #558, Closes #559, Closes #560, Closes #561, Closes #562 --- docs/evidence/CHECKLIST_ACCESSIBILITY.md | 9 ++++++++ docs/evidence/CHECKLIST_CLEAR_LANGUAGE.md | 10 +++++++++ docs/evidence/POLICY_MANUAL_EDIT_ARTIFACTS.md | 20 ++++++++++++++++++ docs/evidence/STANDARD_CODE_BLOCKS.md | 9 ++++++++ docs/evidence/STANDARD_DIAGRAM_STYLE.md | 9 ++++++++ .../STANDARD_ENVIRONMENT_ASSUMPTIONS.md | 15 +++++++++++++ .../STANDARD_GENERATED_FILE_WARNING.md | 21 +++++++++++++++++++ docs/evidence/STANDARD_OUTPUT_EXCERPTS.md | 8 +++++++ docs/evidence/STANDARD_SCREENSHOT_POLICY.md | 9 ++++++++ docs/evidence/STANDARD_TABLE_FORMATTING.md | 8 +++++++ tests/test_standards_batch.py | 20 ++++++++++++++++++ 11 files changed, 138 insertions(+) create mode 100644 docs/evidence/CHECKLIST_ACCESSIBILITY.md create mode 100644 docs/evidence/CHECKLIST_CLEAR_LANGUAGE.md create mode 100644 docs/evidence/POLICY_MANUAL_EDIT_ARTIFACTS.md create mode 100644 docs/evidence/STANDARD_CODE_BLOCKS.md create mode 100644 docs/evidence/STANDARD_DIAGRAM_STYLE.md create mode 100644 docs/evidence/STANDARD_ENVIRONMENT_ASSUMPTIONS.md create mode 100644 docs/evidence/STANDARD_GENERATED_FILE_WARNING.md create mode 100644 docs/evidence/STANDARD_OUTPUT_EXCERPTS.md create mode 100644 docs/evidence/STANDARD_SCREENSHOT_POLICY.md create mode 100644 docs/evidence/STANDARD_TABLE_FORMATTING.md create mode 100644 tests/test_standards_batch.py diff --git a/docs/evidence/CHECKLIST_ACCESSIBILITY.md b/docs/evidence/CHECKLIST_ACCESSIBILITY.md new file mode 100644 index 00000000..40864870 --- /dev/null +++ b/docs/evidence/CHECKLIST_ACCESSIBILITY.md @@ -0,0 +1,9 @@ +# Accessibility Checklist for Docs + +- [ ] Headings use proper hierarchy (h1, h2, h3, not bold text) +- [ ] Links have descriptive text (not "click here") +- [ ] Tables have header rows +- [ ] Code blocks have language tags +- [ ] Color is not the only way to convey information +- [ ] Images have alt text +- [ ] Documents use plain language where possible diff --git a/docs/evidence/CHECKLIST_CLEAR_LANGUAGE.md b/docs/evidence/CHECKLIST_CLEAR_LANGUAGE.md new file mode 100644 index 00000000..9b0f65cd --- /dev/null +++ b/docs/evidence/CHECKLIST_CLEAR_LANGUAGE.md @@ -0,0 +1,10 @@ +# Clear-Language Review Checklist + +- [ ] Avoid jargon where plain language works +- [ ] Define acronyms on first use +- [ ] Use active voice ("the pipeline scores candidates" not "candidates are scored") +- [ ] Keep sentences under 25 words where possible +- [ ] Use bullet points for lists of 3+ items +- [ ] Use numbered steps for procedures +- [ ] Avoid "easily," "simply," "obviously" — these hide complexity +- [ ] Run `check_claims.py` to catch overclaiming language diff --git a/docs/evidence/POLICY_MANUAL_EDIT_ARTIFACTS.md b/docs/evidence/POLICY_MANUAL_EDIT_ARTIFACTS.md new file mode 100644 index 00000000..e1f2d282 --- /dev/null +++ b/docs/evidence/POLICY_MANUAL_EDIT_ARTIFACTS.md @@ -0,0 +1,20 @@ +# Manual-Edit Policy for Artifacts + +Some artifacts are generated by the pipeline and should not be edited manually. + +## Do Not Edit +- Schema files in `schemas/` — edit the source code that produces them +- Generated documentation — edit the source doc, not the generated copy +- Benchmark output files in `outputs/` — regenerate with `make bench-*` +- Evidence certificates — re-run the ranking pipeline + +## May Edit +- Configuration files in `configs/` (with review) +- Documentation in `docs/` (with review for new docs) +- Test files in `tests/` (with review) +- Scripts in `scripts/` (with review) + +## Rules +- If a file has a "generated" warning, do not edit it directly +- When in doubt, check the file header for instructions +- If you must edit a generated file, add a comment explaining why diff --git a/docs/evidence/STANDARD_CODE_BLOCKS.md b/docs/evidence/STANDARD_CODE_BLOCKS.md new file mode 100644 index 00000000..e1504a75 --- /dev/null +++ b/docs/evidence/STANDARD_CODE_BLOCKS.md @@ -0,0 +1,9 @@ +# Code Block Standard for Commands + +- Use `bash` language tag for shell commands +- Use `python` language tag for Python examples +- Use `json` for JSON examples +- Use `text` for output that is not code +- Every command example should be runnable from a clean checkout +- Include the expected output format, not the exact output +- Use `$` prefix for commands, no `$` prefix for output diff --git a/docs/evidence/STANDARD_DIAGRAM_STYLE.md b/docs/evidence/STANDARD_DIAGRAM_STYLE.md new file mode 100644 index 00000000..48d0846c --- /dev/null +++ b/docs/evidence/STANDARD_DIAGRAM_STYLE.md @@ -0,0 +1,9 @@ +# Diagram Source Style Guide + +- Use Mermaid for diagrams (flowchart, sequence, component) +- Keep diagrams in markdown code blocks with the mermaid language tag +- Place diagrams near the relevant text, not in a separate file +- Label all nodes clearly +- Limit to 15 nodes per diagram +- Use `flowchart TD` for top-down, `flowchart LR` for left-right +- Use `-->` for directed edges, `---` for undirected diff --git a/docs/evidence/STANDARD_ENVIRONMENT_ASSUMPTIONS.md b/docs/evidence/STANDARD_ENVIRONMENT_ASSUMPTIONS.md new file mode 100644 index 00000000..9f68c6ec --- /dev/null +++ b/docs/evidence/STANDARD_ENVIRONMENT_ASSUMPTIONS.md @@ -0,0 +1,15 @@ +# Environment Assumption Standard + +Every document should state its assumptions about the reader's environment. + +## Required +- Python version (minimum: 3.11) +- Operating system (tested on: macOS, Linux) +- Working `git` installation +- Working `make` installation + +## Optional but recommended +- Virtual environment manager (venv) +- RAM (minimum: 4 GB, recommended: 8 GB) +- Disk space (minimum: 500 MB) +- Network access (required for `pip install`, optional for local checks) diff --git a/docs/evidence/STANDARD_GENERATED_FILE_WARNING.md b/docs/evidence/STANDARD_GENERATED_FILE_WARNING.md new file mode 100644 index 00000000..f76e1e3b --- /dev/null +++ b/docs/evidence/STANDARD_GENERATED_FILE_WARNING.md @@ -0,0 +1,21 @@ +# Generated-File Warning Standard + +Files that are generated by scripts or CI must carry a warning. + +## Warning Format + +```markdown +> **NOTE:** This file is generated. Do not edit directly. +> Source: [path to source script or config] +> Regenerate with: `make [target]` +``` + +## Where to Apply +- Benchmark output files (if committed) +- Generated documentation +- Auto-generated configs +- CI-generated artifacts + +## Exceptions +- Files that are both source and output (e.g., README.md that is also generated) +- Files in `outputs/` which are git-ignored diff --git a/docs/evidence/STANDARD_OUTPUT_EXCERPTS.md b/docs/evidence/STANDARD_OUTPUT_EXCERPTS.md new file mode 100644 index 00000000..a4727406 --- /dev/null +++ b/docs/evidence/STANDARD_OUTPUT_EXCERPTS.md @@ -0,0 +1,8 @@ +# Command Output Excerpt Standard + +- Show only the relevant portion of command output, not the full output +- Use `...` to indicate omitted content +- Label the excerpt with the command that produced it +- If the output is machine-readable (JSON), show it as a code block +- If the output is human-readable, show it as a text block +- Annotate important parts with comments where helpful diff --git a/docs/evidence/STANDARD_SCREENSHOT_POLICY.md b/docs/evidence/STANDARD_SCREENSHOT_POLICY.md new file mode 100644 index 00000000..42ee2771 --- /dev/null +++ b/docs/evidence/STANDARD_SCREENSHOT_POLICY.md @@ -0,0 +1,9 @@ +# Screenshot and Image Policy + +- Avoid screenshots — use Mermaid diagrams instead +- If a screenshot is necessary, use PNG format +- Keep images under 500 KB +- Do not include screenshots of code — use code blocks instead +- Do not include screenshots of terminal output — use text blocks instead +- Alt text is required for all images +- Store images in `docs/assets/` diff --git a/docs/evidence/STANDARD_TABLE_FORMATTING.md b/docs/evidence/STANDARD_TABLE_FORMATTING.md new file mode 100644 index 00000000..6d002b4d --- /dev/null +++ b/docs/evidence/STANDARD_TABLE_FORMATTING.md @@ -0,0 +1,8 @@ +# Table Formatting Standard + +- Use pipe tables (`| col | col |`) +- Include a separator row after the header +- Align columns with `:---` (left), `:---:` (center), `---:` (right) +- No empty cells — use `—` or `N/A` instead +- Keep tables under 8 columns wide +- Break long tables into multiple smaller tables where possible diff --git a/tests/test_standards_batch.py b/tests/test_standards_batch.py new file mode 100644 index 00000000..fbcebc9e --- /dev/null +++ b/tests/test_standards_batch.py @@ -0,0 +1,20 @@ +"""Tests for 10 standards and policies.""" +from pathlib import Path + +FILES = [ + "STANDARD_TABLE_FORMATTING.md", + "STANDARD_DIAGRAM_STYLE.md", + "STANDARD_SCREENSHOT_POLICY.md", + "CHECKLIST_ACCESSIBILITY.md", + "CHECKLIST_CLEAR_LANGUAGE.md", + "STANDARD_CODE_BLOCKS.md", + "STANDARD_OUTPUT_EXCERPTS.md", + "STANDARD_ENVIRONMENT_ASSUMPTIONS.md", + "STANDARD_GENERATED_FILE_WARNING.md", + "POLICY_MANUAL_EDIT_ARTIFACTS.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"