Validation and Quality Assurance
Validation and Quality Assurance
Build confidence in documentation quality through structured validation, measurable metrics, and continuous improvement
Table of Contents
Introduction
Documentation quality isn’t subjective—it can be measured, validated, and improved systematically. This article presents frameworks for assessing and ensuring documentation quality.
This article covers:
- Validation frameworks - Structured approaches to quality assessment
- Seven dimensions - Grammar, readability, structure, fact accuracy, logical coherence, coverage, and references
- Review processes - Human review workflows that improve quality
- Quality metrics - Measurable indicators of documentation health
- Automation - Tools that scale validation efforts
- Continuous improvement - Workflows that prevent quality regression
Why validation matters: Inaccurate documentation erodes trust. Users who find one error question everything else. Systematic validation builds and maintains credibility.
Prerequisites: Familiarity with writing style, structure, and code documentation.
Validation Frameworks
Different organizations approach documentation validation differently. Understanding multiple frameworks helps you build the right approach for your context.
The Documentation Quality Triangle
Documentation quality balances three concerns:
Accuracy
△
/ \
/ \
/ \
/________\
Clarity Completeness
Accuracy: Information is correct and current Clarity: Information is understandable Completeness: Information is sufficient for user needs
Trade-offs exist:
- Maximum accuracy may sacrifice clarity (technical precision vs. accessibility)
- Maximum completeness may sacrifice clarity (information overload)
- Maximum clarity may sacrifice completeness (oversimplification)
Wikipedia’s Good Article Criteria
Wikipedia’s Good Article criteria provide a tested framework:
- Well-written - Clear, concise prose following style guides
- Verifiable - Claims cited to reliable sources
- Broad coverage - Topic covered comprehensively without major gaps
- Neutral - Fair representation without bias
- Stable - Not subject to ongoing edit wars
- Illustrated - Images have appropriate captions and licenses
Application to technical documentation: | Wikipedia Criterion | Technical Doc Equivalent | |———————|————————–| | Well-written | Grammar, readability, style | | Verifiable | Accurate technical claims, working code | | Broad coverage | Complete API coverage, all use cases | | Neutral | Objective technical presentation | | Stable | Versioned, change-tracked | | Illustrated | Diagrams, screenshots, code examples |
Google’s QUAC Framework
Google uses QUAC for documentation quality:
- Quality - Technical accuracy and completeness
- Usability - Can users accomplish their goals?
- Accessibility - Works for all users
- Consistency - Follows established patterns
Microsoft’s Five Pillars
Microsoft documentation emphasizes:
- Accuracy - Technically correct
- Completeness - All information present
- Clarity - Understandable writing
- Task orientation - Helps users accomplish goals
- Consistency - Follows style guide
The Seven Validation Dimensions
This repository uses seven validation dimensions, documented in validation-criteria.md.
Dimension 1: Grammar
What it measures: Language correctness—spelling, grammar, punctuation, syntax
Quality indicators:
- No spelling errors
- Correct subject-verb agreement
- Proper punctuation
- Consistent capitalization
- Correct word usage (their/there/they’re)
Validation approach:
- Automated spell-check
- Grammar checker (Grammarly, LanguageTool)
- Human review for context-dependent issues
Reference prompt: grammar-review.prompt.md
Dimension 2: Readability
What it measures: How easily text can be understood
Quality indicators (targets):
- Flesch Reading Ease: 50-70 (plain English)
- Flesch-Kincaid Grade: 9-10 (high school level)
- Sentence length: 15-25 words average
- Paragraph length: 3-5 sentences
- Active voice: 75-85%
Validation approach:
- Calculate readability scores
- Identify overly complex sentences
- Flag passive voice overuse
- Check for jargon density
Reference prompt: readability-review.prompt.md
Dimension 3: Structure
What it measures: Organization and navigation effectiveness
Quality indicators:
- Logical heading hierarchy (no skipped levels)
- Clear introduction stating scope
- Conclusion summarizing key points
- Effective use of lists and tables
- Appropriate cross-references
Validation approach:
- Check heading hierarchy
- Verify introduction/conclusion presence
- Assess information flow
- Validate internal links
Dimension 4: Fact Accuracy
What it measures: Technical correctness of claims
Quality indicators:
- Code examples work as written
- Version numbers are current
- Links resolve correctly
- Technical claims are accurate
- Commands produce expected results
Validation approach:
- Test all code examples
- Verify version information
- Check all links
- Expert review for technical claims
This is the hardest dimension to automate. Fact accuracy often requires:
- Domain expertise
- Running code in context
- Access to systems described
- Knowledge of recent changes
Dimension 5: Logical Coherence
What it measures: Argument flow and reasoning consistency
Quality indicators:
- Ideas flow logically
- Transitions connect sections
- No contradictions
- Assumptions stated explicitly
- Prerequisites identified
Validation approach:
- Read for argument flow
- Check for contradictions
- Verify logical connections
- Identify unstated assumptions
Dimension 6: Coverage
What it measures: Completeness relative to topic scope
Quality indicators:
- All relevant subtopics addressed
- No major gaps
- Edge cases covered
- Error scenarios documented
- Prerequisites documented
Validation approach:
- Compare against topic outline
- Check for missing scenarios
- Verify prerequisite documentation
- Gap analysis against similar resources
Dimension 7: References
What it measures: Citation quality and source reliability
Quality indicators:
- Claims supported by references
- Sources are authoritative
- References are current
- Links are functional
- Reference classification accurate (📘📗📒📕)
Validation approach:
- Verify all links
- Assess source authority
- Check publication dates
- Validate classification markers
Reference classification system: | Marker | Category | Sources | |——–|———-|———| | 📘 | Official | Microsoft Learn, vendor documentation | | 📗 | Verified Community | Peer-reviewed, established blogs | | 📒 | Community | Personal blogs, forums | | 📕 | Unverified | Broken links, unknown sources |
Review Processes
Automated validation catches mechanical issues. Human review catches conceptual issues, audience mismatches, and subtle errors.
Types of Documentation Review
Self-review: Author reviews own work after time gap
- Effective for catching obvious errors
- Limited by author’s blind spots
Peer review: Colleague reviews before publication
- Catches clarity issues (what’s clear to author may not be clear to reader)
- May miss technical accuracy issues
Expert review: Subject matter expert validates technical content
- Essential for fact accuracy
- Often bottleneck in process
User testing: Target audience attempts to use documentation
- Gold standard for usability
- Most expensive and time-consuming
Review Checklist
Before submitting for review:
During peer review, check:
During expert review, verify:
Review Feedback Guidelines
For reviewers:
- Be specific (not “this is confusing” but “the relationship between X and Y is unclear”)
- Suggest solutions when possible
- Distinguish required changes from suggestions
- Focus on the work, not the author
For authors:
- Respond to all feedback
- Ask for clarification if needed
- Explain reasoning for disagreements
- Thank reviewers
Quality Metrics
Metrics make quality visible and improvable over time.
Quantitative Metrics
Readability metrics:
Flesch Reading Ease = 206.835 - 1.015(words/sentences) - 84.6(syllables/words)
Flesch-Kincaid Grade = 0.39(words/sentences) + 11.8(syllables/words) - 15.59
Structural metrics:
- Average section length
- Heading depth distribution
- Code-to-prose ratio
- Links per 1000 words
Coverage metrics:
- API coverage percentage
- Error scenario coverage
- Feature documentation coverage
Currency metrics:
- Average document age
- Documents updated in last 90 days
- Percentage with verified links
Qualitative Metrics
User feedback:
- Documentation satisfaction scores
- “Was this helpful?” responses
- Support ticket mentions of documentation
Search metrics:
- Search queries with no results
- Most-viewed pages
- Pages with high bounce rates
Maintenance metrics:
- Time to update after product change
- Review cycle time
- Validation pass rate
Metric Targets for This Repository
From validation-criteria.md:
| Metric | Target | Measurement |
|---|---|---|
| Flesch Reading Ease | 50-70 | Per article |
| Flesch-Kincaid Grade | 9-10 | Per article |
| Active Voice | 75-85% | Per article |
| Sentence Length | 15-25 words | Average per article |
| Link Validity | 100% | Site-wide |
| Reference Classification | 100% classified | Per article |
Automated Validation
Automation scales validation and provides consistency.
What to Automate
High automation potential:
- Spell-checking
- Grammar checking
- Link validation
- Readability scoring
- Heading hierarchy validation
- Style guide compliance
Medium automation potential:
- Code example syntax checking
- Terminology consistency
- Reference format validation
- Structure template compliance
Low automation potential:
- Fact accuracy
- Logical coherence
- Audience appropriateness
- Completeness for purpose
Validation Tools
Text quality:
- Vale - Prose linting with custom rules
- LanguageTool - Grammar and style checking
- textstat - Readability scoring (Python)
- write-good - English prose suggestions
Link checking:
- markdown-link-check - Validates markdown links
- linkchecker - Comprehensive link validation
- Repository scripts - check-links.ps1
Documentation-specific:
- Sphinx - Documentation build validation
- MkDocs - Static site generation with validation
- Quarto - This repository’s rendering engine
Implementing Validation Pipeline
# Example CI/CD validation workflow
name: Documentation Validation
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check spelling
uses: streetsidesoftware/cspell-action@v5
- name: Validate links
uses: gaurav-nelson/github-action-markdown-link-check@v1
- name: Check style
run: vale .
- name: Build documentation
run: quarto renderIQPilot Validation Tools
This repository’s IQPilot MCP server provides validation tools:
Available tools:
- Grammar validation
- Readability analysis
- Structure validation
- Reference classification check
- Cross-reference validation
- Gap analysis
Usage pattern:
- Author writes/updates documentation
- Runs validation via natural language (“validate grammar for this article”)
- Tool checks content against criteria
- Results cached to avoid redundant validation
- Metadata updated with validation status
Continuous Improvement
Quality isn’t a destination—it’s a process.
The Quality Improvement Cycle
┌─────────────┐
│ Measure │
└──────┬──────┘
│
▼
┌─────────────┐
│ Analyze │
└──────┬──────┘
│
▼
┌─────────────┐
│ Improve │
└──────┬──────┘
│
▼
┌─────────────┐
│ Validate │
└──────┬──────┘
│
└──────► (repeat)
Measure: Collect metrics on current state Analyze: Identify patterns and root causes Improve: Make targeted changes Validate: Verify improvement achieved
Documentation Debt
Like technical debt, documentation debt accumulates:
Types of documentation debt:
- Accuracy debt - Information that’s become outdated
- Coverage debt - Features lacking documentation
- Quality debt - Content that doesn’t meet standards
- Structural debt - Organization that’s grown inconsistent
Managing documentation debt:
- Track known issues (documentation issue backlog)
- Prioritize by user impact
- Allocate time for debt reduction
- Prevent new debt (validation in workflow)
Validation-Driven Workflows
Pre-publish validation:
- Author completes draft
- Runs automated validation
- Fixes identified issues
- Submits for review
- Reviewer validates changes
- Publish
Post-publish monitoring:
- Track user feedback
- Monitor link health
- Check for outdated content
- Schedule periodic reviews
Triggered updates:
- Product change triggers documentation review
- Identified gaps added to backlog
- Validation confirms completeness
Validation in This Repository
Validation Metadata System
Each article tracks validation status in bottom YAML:
<!-- Validation Metadata
validation_status: validated_clean # or pending, needs_review
validation_history:
grammar:
last_run: "2026-01-14"
status: pass
score: 95
readability:
last_run: "2026-01-10"
status: pass
score: 68 # Flesch Reading Ease
grade: 9.5 # Flesch-Kincaid
-->Validation Prompts
Located in .github/prompts/:
Core validation prompts:
grammar-review.prompt.md- Grammar validationreadability-review.prompt.md- Readability analysisstructure-review.prompt.md- Structure validationfact-check.prompt.md- Fact accuracy review
Usage:
Run grammar-review.prompt on this article
Validation Caching
IQPilot caches validation results to avoid redundant processing:
- Cache duration: 7 days (configurable)
- Cache invalidation: Content changes
- Cache key: File path + content hash
Rationale: Validation (especially AI-powered) can be expensive. Caching reduces costs while maintaining freshness.
Reference Validation
All references should use classification markers:
Validation checks:
- All external links have markers
- Markers match source types
- No 📕 markers in published content
- Links resolve correctly
Reference template:
**[Title](url)** 📘 [Official]
Brief description of content and relevance.Conclusion
Documentation validation transforms quality from aspiration to achievement. Key principles:
Multiple dimensions matter - Grammar, readability, structure, accuracy, coherence, coverage, and references each contribute to quality
Combine automation with human review - Automation catches mechanical issues; humans catch conceptual issues
Measure to improve - Metrics make quality visible and enable targeted improvement
Build validation into workflow - Validate before publishing, monitor after publishing
Treat documentation debt seriously - Track and address quality gaps systematically
Use frameworks consistently - Wikipedia’s criteria, the quality triangle, and this repository’s seven dimensions provide tested approaches
Next in series:
- 06-citations-and-reference-management.md - Deep dive into reference validation
- 07-ai-enhanced-documentation-writing.md - AI-powered validation approaches
- 01-writing-style-and-voice-principles.md - Readability principles
References
Quality Frameworks
Wikipedia Good Article Criteria 📘 [Official]
Wikipedia’s criteria for quality articles, applicable to documentation quality assessment.
Wikipedia Featured Article Criteria 📘 [Official]
Wikipedia’s highest quality standard, providing aspirational quality criteria.
Google Developer Documentation Style Guide - Quality 📘 [Official]
Google’s documentation quality standards and guidelines.
Microsoft Writing Quality 📘 [Official]
Microsoft’s quality principles for documentation.
Validation Tools
Vale - A Linter for Prose 📗 [Verified Community]
Open-source prose linter with customizable rules.
LanguageTool 📗 [Verified Community]
Grammar and style checker supporting multiple languages.
textstat (Python) 📗 [Verified Community]
Python library for calculating text readability metrics.
markdown-link-check 📗 [Verified Community]
Tool for validating links in markdown files.
Metrics and Measurement
Flesch Reading Ease 📘 [Official]
Wikipedia’s explanation of Flesch readability formulas.
Plain Language Action and Information Network 📘 [Official]
US government guidance on testing document readability.
Review Processes
Google Engineering Practices - Code Review 📘 [Official]
Google’s code review guidelines, applicable to documentation review.
Write the Docs - Documentation Review 📗 [Verified Community]
Community guidance on documentation review as part of docs-as-code.
Repository-Specific Documentation
Validation Criteria [Internal Reference]
This repository’s seven validation dimensions and quality targets.
Grammar Review Prompt [Internal Reference]
Prompt file for grammar validation.
IQPilot README [Internal Reference]
MCP server providing validation tools.
Link Check Script [Internal Reference]
PowerShell script for link validation.