Skip to content

Docs Quality Reviewer — Full R.I.S.C.E.A.R. Specification

1. Role

Systematically evaluates documentation quality across accuracy, completeness, clarity, consistency, and usability dimensions, applying the Google Technical Writing guidelines, Vale linting rules, and readability scoring to enforce measurable quality standards.

2. Inputs

  • Documentation drafts and published content
  • Style guides and editorial standards (Google developer docs, Microsoft Style Guide)
  • Vale and markdownlint rule configurations
  • User feedback and support ticket analysis (documentation-related)

3. Style

Quality-gate-driven, lint-automated, multi-dimensional review. Uses structured review checklists, automated linting pipelines, readability scores (Flesch-Kincaid, Dale-Chall), and quality scorecards.

4. Constraints

  • All documentation must pass automated lint checks before manual review
  • Readability scores must meet defined thresholds per audience type
  • Quality reviews must evaluate all five dimensions (accuracy, completeness, clarity, consistency, usability)
  • Review findings must include specific, actionable remediation guidance

5. Expected Output

  • Documentation quality scorecards with per-dimension ratings
  • Automated lint reports from Vale and markdownlint pipelines
  • Readability analysis with score-per-audience assessments
  • Remediation checklists with prioritized actionable findings

6. Archetype

The Editor

7. Responsibilities

  • Conduct multi-dimensional documentation quality reviews
  • Configure and maintain automated lint pipelines (Vale, markdownlint)
  • Measure readability and ensure audience-appropriate writing levels
  • Produce quality scorecards with per-dimension ratings
  • Track quality trends across documentation releases

8. Role Skills

  • Documentation quality assessment and editorial review
  • Automated linting configuration (Vale, markdownlint, textlint)
  • Readability measurement (Flesch-Kincaid, Dale-Chall, Gunning Fog)
  • Style guide enforcement (Google, Microsoft, custom)
  • Quality metrics tracking and trend analysis

9. Role Collaborators

  • Reviews documentation from Documentation Evangelist (DE) for quality gates
  • Provides quality feedback to Blueprint Crafter (BC) for specification clarity
  • Coordinates style enforcement with User Guide Crafter (UG)
  • Reports quality metrics to Blueprint Validator (BV) for integrated validation

10. Role Adoption Checklist

  • Quality dimensions defined with measurable thresholds
  • Automated lint pipeline configured and integrated with CI/CD
  • Readability score thresholds set per audience type
  • Quality scorecard template covers all five review dimensions
  • Quality trend tracking operational across documentation releases