# Lerianstudio Ring Documentation Review > Documentation Review Process - Skill: `tomevault-io/lerianstudio-ring-documentation-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-documentation-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-documentation-review/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lerianstudio-ring-documentation-review --- # Documentation Review Process Review documentation systematically across multiple dimensions. A thorough review catches issues before they reach users. ## Review Dimensions 1. **Voice and Tone** – Does it sound right? 2. **Structure** – Is it organized effectively? 3. **Completeness** – Is everything covered? 4. **Clarity** – Is it easy to understand? 5. **Technical Accuracy** – Is it correct? --- ## Voice and Tone Review | Check | Flag If | |-------|---------| | Second person | "Users can..." instead of "You can..." | | Present tense | "will return" instead of "returns" | | Active voice | "is returned by the API" instead of "The API returns" | | Tone | Arrogant ("Obviously...") or condescending | --- ## Structure Review | Check | Flag If | |-------|---------| | Hierarchy | Deep nesting (H4+), unclear parent-child | | Headings | Title Case instead of sentence case | | Section dividers | Missing `---` between major topics | | Navigation | Missing links to related content | --- ## Completeness Review **Conceptual docs:** Definition, characteristics, how it works, related concepts, next steps **How-to guides:** Prerequisites, all steps, verification, troubleshooting, next steps **API docs:** HTTP method/path, all parameters, all fields, required vs optional, examples, error codes --- ## Clarity Review | Check | Flag If | |-------|---------| | Sentence length | >25 words per sentence | | Paragraph length | >3 sentences per paragraph | | Jargon | Technical terms not explained on first use | | Examples | Abstract data ("foo", "bar") instead of realistic | --- ## Technical Accuracy Review **Conceptual:** Facts correct, behavior matches description, links work **API docs:** Paths correct, methods correct, field names match API, types accurate, examples valid JSON **Code examples:** Compiles/runs, output matches description, no syntax errors --- ## Common Issues to Flag | Category | Issue | Fix | |----------|-------|-----| | Voice | Third person ("Users can...") | "You can..." | | Voice | Passive ("...is returned") | "...returns" | | Voice | Future tense ("will provide") | "provides" | | Structure | Title case heading | Sentence case | | Structure | Wall of text | Add `---` dividers | | Completeness | Missing prereqs | Add prerequisites | | Completeness | No examples | Add code examples | | Clarity | Long sentences (40+ words) | Split into multiple | | Clarity | Undefined jargon | Define on first use | --- ## Review Output Format > **Note:** Documentation reviews use `PASS/NEEDS_REVISION/MAJOR_ISSUES` verdicts (graduated), which differ from code review verdicts (`PASS/FAIL/NEEDS_DISCUSSION`). ```markdown ## Review Summary **Overall Assessment:** [PASS | NEEDS_REVISION | MAJOR_ISSUES] ### Issues Found #### High Priority 1. **Line 45:** Passive voice "is created by" → "creates" #### Medium Priority 1. **Line 23:** Title case in heading → sentence case #### Low Priority 1. **Line 12:** Could add example for clarity ### Recommendations 1. Fix passive voice instances (3 found) 2. Add missing API field documentation ``` --- ## Quick Review Checklist **Voice (30s):** "You" not "users", present tense, active voice **Structure (30s):** Sentence case headings, section dividers, scannable (bullets/tables) **Completeness (1m):** Examples present, links work, next steps included **Accuracy (varies):** Technical facts correct, code examples work --- ## Standards Loading (MANDATORY) Before reviewing documentation: 1. **Load voice and tone** - `ring:voice-and-tone` for style verification 2. **Load structure patterns** - `ring:documentation-structure` for organization checks 3. **Load document type patterns** - `ring:writing-functional-docs` or `ring:writing-api-docs` **HARD GATE:** CANNOT review documentation without loading relevant standards. --- ## Blocker Criteria - STOP and Report | Condition | Decision | Action | |-----------|----------|--------| | Style guide unavailable | STOP | Report: "Need style guide to review against" | | Source material missing | STOP | Report: "Need source to verify technical accuracy" | | Review scope undefined | STOP | Report: "Need to know what aspects to review" | | Technical SME unavailable | STOP | Report: "Need SME access for accuracy verification" | ### Cannot Be Overridden These requirements are NON-NEGOTIABLE: - MUST review all five dimensions (voice, structure, completeness, clarity, accuracy) - MUST flag all issues found (not just major ones) - MUST provide specific line references for issues - MUST categorize issues by priority (High/Medium/Low) - CANNOT approve documentation with HIGH-priority issues - CANNOT skip accuracy verification --- ## Severity Calibration | Severity | Criteria | Examples | |----------|----------|----------| | **CRITICAL** | Factually incorrect, misleading information | Wrong API paths, incorrect behavior described | | **HIGH** | Major voice/structure violations, missing sections | Passive voice throughout, no examples | | **MEDIUM** | Multiple minor issues, inconsistencies | Mixed pronouns, some title case | | **LOW** | Polish issues, optimization opportunities | Could flow better, minor wording | --- ## Pressure Resistance | User Says | Your Response | |-----------|---------------| | "Just do a quick review, we're rushing" | "Quick review still covers all 5 dimensions. CANNOT skip any review category." | | "Only check for typos" | "Review MUST cover voice, structure, completeness, clarity, AND accuracy. Typos are LOW priority." | | "Skip technical accuracy, trust the writer" | "Technical accuracy MUST be verified. Trust but verify." | | "Approve it, minor issues can be fixed later" | "CANNOT approve with HIGH priority issues. They must be fixed first." | | "The content is more important than style" | "Style affects comprehension. Voice and tone are REQUIRED review dimensions." | --- ## Anti-Rationalization Table | Rationalization | Why It's WRONG | Required Action | |-----------------|----------------|-----------------| | "Good enough for now" | Good enough ≠ meets standards | **MUST flag all issues** | | "Writer knows the product" | Knowledge ≠ documentation quality | **Review all dimensions** | | "Style issues are subjective" | Style guidelines are objective standards | **Apply guidelines consistently** | | "Users won't notice minor issues" | Minor issues accumulate into poor UX | **Flag all issues regardless of size** | | "Review is blocking release" | Poor docs also block user success | **Complete review properly** | | "Trust the automated checks" | Automated checks miss context | **Human review is REQUIRED** | --- ## When This Skill is Not Needed Signs that documentation doesn't need review: - Documentation was written by ring-tw-team specialists - Previous review found zero issues - Documentation hasn't changed since last review - All five review dimensions already verified **If all above are true:** Review may be skipped for unchanged content. **Note:** New or modified documentation MUST always be reviewed. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.