Skip to content

Documentation Checklists

Quality assurance checklists for creating and reviewing documentation.

General Documentation Checklist

Content Quality

  • Accuracy: Information is correct and up-to-date
  • Completeness: All necessary information included
  • Clarity: Language is clear and unambiguous
  • Consistency: Terminology and style are uniform
  • Relevance: Content matches user needs

Structure

  • Organization: Logical flow and hierarchy
  • Navigation: Easy to find information
  • Headings: Descriptive and properly nested
  • Sections: Appropriately sized and focused
  • Cross-references: Links to related content

Technical Aspects

  • Code Examples: Tested and working
  • Commands: Accurate and properly formatted
  • Screenshots: Current and clearly labeled
  • Diagrams: Helpful and properly explained
  • Version Info: Clearly stated

Diátaxis-Specific Checklists

Tutorial Checklist

  • Learning Focus: Teaches concepts, not just tasks
  • Complete Project: Results in something meaningful
  • No Assumptions: Explains everything needed
  • Sequential Steps: Clear progression
  • Concrete Examples: Real, working code
  • Exercises: Opportunities to practice
  • Next Steps: Where to go after completion

How-To Guide Checklist

  • Task-Oriented: Focuses on specific goal
  • Prerequisites Listed: Clear requirements
  • Step-by-Step: Numbered, actionable steps
  • Multiple Approaches: Where applicable
  • Troubleshooting: Common problems addressed
  • Verification: How to confirm success
  • Time Estimate: How long it takes

Reference Checklist

  • Factual: No opinions or recommendations
  • Complete: All parameters/options documented
  • Searchable: Good keywords and structure
  • Consistent Format: Predictable organization
  • Examples: Brief, illustrative examples
  • Cross-References: Links to related items
  • Technical Accuracy: Verified information

Explanation Checklist

  • Conceptual: Focuses on understanding
  • Context: Background and bigger picture
  • Connections: Links between concepts
  • Examples: Analogies and illustrations
  • Alternative Views: Different perspectives
  • No Instructions: Understanding, not doing
  • Further Reading: Additional resources

Review Process Checklist

Before Review

  • Self-Review: Author has reviewed
  • Spell Check: Run and corrections made
  • Link Check: All links verified
  • Format Check: Follows style guide
  • Examples Tested: Code/commands work

During Review

  • Target Audience: Appropriate level
  • Completeness: Nothing missing
  • Clarity: Easy to understand
  • Technical Accuracy: Facts verified
  • Consistency: Matches other docs

After Review

  • Feedback Addressed: All comments resolved
  • Changes Tested: Updates verified
  • Final Check: One last read-through
  • Metadata Updated: Version, date, etc.
  • Published: Deployed to users

Style and Formatting Checklist

Writing Style

  • Active Voice: Direct and clear
  • Present Tense: Current and immediate
  • Short Sentences: Easy to parse
  • Simple Words: Avoid unnecessary jargon
  • Consistent Terms: Same word for same thing

Formatting

  • Headings: Proper hierarchy (H1, H2, H3)
  • Lists: Bullets or numbers as appropriate
  • Code Blocks: Properly formatted with language
  • Emphasis: Bold for UI, code for commands
  • White Space: Adequate spacing

Visual Elements

  • Images: Compressed and optimized
  • Alt Text: Descriptive for accessibility
  • Captions: Where needed
  • Diagrams: Vector format when possible
  • Annotations: Clear labels

Accessibility Checklist

  • Alt Text: All images have descriptions
  • Heading Structure: Logical and sequential
  • Link Text: Descriptive, not "click here"
  • Color Contrast: Sufficient for readability
  • Table Headers: Properly marked
  • Language: Simple and clear
  • Abbreviations: Defined on first use

Maintenance Checklist

Regular Reviews

  • Quarterly Review: Check for outdated info
  • Link Validation: Monthly automated check
  • User Feedback: Review and address
  • Analytics Review: Check usage patterns
  • Update History: Maintain changelog

Version Updates

  • Product Changes: Reflect new features
  • API Updates: Match current version
  • Deprecations: Mark outdated features
  • Migration Guides: For breaking changes
  • Archive Old Versions: Maintain history

Quick Start Checklist

For new documentation:

  1. Identify documentation type (tutorial/how-to/reference/explanation)
  2. Use appropriate template
  3. Write first draft
  4. Self-review with checklist
  5. Test all examples
  6. Request peer review
  7. Address feedback
  8. Final review
  9. Publish
  10. Monitor feedback

See Also