Skip to main content

Documentation Verification

Automated system for tracking and managing documentation freshness with last_verified dates.

Overview​

The documentation verification system helps maintain up-to-date documentation by tracking when each page was last reviewed and flagging outdated docs. It uses frontmatter fields to store verification dates and provides commands to check, update, and report on documentation status.

Features​

  • 📅 Automatic verification tracking - Add last_verified dates to frontmatter
  • ⚠️ Outdated doc detection - Flag docs older than threshold (default: 90 days)
  • 📊 Detailed reporting - See which docs need review
  • 🔄 Batch updates - Update verification dates for multiple files
  • 🤖 Auto-add mode - Automatically add missing verification dates

Usage​

Check documentation status​

npm run verify-docs

Generate detailed report​

npm run verify-docs:report
# or
node scripts/verify-docs.cjs report

Update verification date for files​

# Single file
node scripts/verify-docs.cjs update docs/architecture.md

# Multiple files
node scripts/verify-docs.cjs update docs/architecture.md docs/intro.md

# Use npm script (for single file)
npm run verify-docs:update docs/architecture.md

Check with custom threshold​

# Flag docs older than 60 days
node scripts/verify-docs.cjs check --days 60

# Flag docs older than 180 days
node scripts/verify-docs.cjs check --days=180

Auto-add verification dates​

# Automatically add today's date to files missing last_verified
node scripts/verify-docs.cjs check --auto-add

Include tools/ directory​

# Check both docs/ and tools/ directories
node scripts/verify-docs.cjs check --include-tools

JSON output for CI/CD​

node scripts/verify-docs.cjs report --format json

Example output​

📋 Documentation Verification Script

Checking 57 files...
Threshold: 90 days

============================================================
DOCUMENTATION VERIFICATION REPORT
============================================================

Total files checked: 57
Verification threshold: 90 days

📊 Summary:
  ✅ Up to date: 42
  ⚠️  Outdated: 8
  ❓ Missing verification: 7
  ❌ Errors: 0

⚠️  OUTDATED DOCUMENTATION

  docs/architecture.md
    Last verified: 2025-10-15 (120 days ago)
    Update command: node scripts/verify-docs.cjs update docs/architecture.md

  docs/tools.md
    Last verified: 2025-09-01 (150 days ago)
    Update command: node scripts/verify-docs.cjs update docs/tools.md

❓ MISSING VERIFICATION DATES

  docs/new-guide.md
    Reason: No last_verified field
    Add command: node scripts/verify-docs.cjs update docs/new-guide.md

✅ All documentation is up to date!

Frontmatter format​

Add the last_verified field to your document frontmatter:

---
id: my-doc
title: My Documentation
last_verified: 2026-01-06
---

Date format​

Use ISO 8601 date format: YYYY-MM-DD

# ✅ Correct
last_verified: 2026-01-06

# ❌ Wrong
last_verified: 01/06/2026
last_verified: January 6, 2026
last_verified: 2026-1-6

Commands​

check​

Check for outdated documentation and display summary.

node scripts/verify-docs.cjs check [options]

Options:

  • --days <n> - Flag docs older than n days (default: 90)
  • --include-tools - Include tools/ source directory
  • --auto-add - Automatically add missing verification dates
  • --format json - Output as JSON

update​

Update verification date for one or more files to today's date.

node scripts/verify-docs.cjs update <file1> [file2] [...]

report​

Generate detailed verification report.

node scripts/verify-docs.cjs report [options]

Options:

  • --days <n> - Flag docs older than n days (default: 90)
  • --include-tools - Include tools/ source directory
  • --format json - Output as JSON

Workflow examples​

Weekly documentation review​

# 1. Check what needs review
npm run verify-docs

# 2. Review and update specific docs
vim docs/architecture.md
node scripts/verify-docs.cjs update docs/architecture.md

# 3. Generate report for team
node scripts/verify-docs.cjs report > verification-report.txt

Monthly documentation audit​

# Check docs older than 30 days
node scripts/verify-docs.cjs check --days 30

# Review flagged docs
# ... edit files ...

# Batch update after review
node scripts/verify-docs.cjs update \
  docs/architecture.md \
  docs/tools.md \
  docs/intro.md

New documentation setup​

# Add verification dates to all docs
node scripts/verify-docs.cjs check --auto-add

Integration with workflows​

Git pre-commit hook​

Add to .husky/pre-commit:

#!/bin/sh
# Check for outdated docs (90 days)
cd docusaurus && npm run verify-docs

GitHub Actions​

Add to .github/workflows/check-docs.yml:

name: Check Documentation Freshness

on:
  schedule:
    - cron: '0 0 * * 1'  # Every Monday
  workflow_dispatch:

jobs:
  verify-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: cd docusaurus && npm ci
      - run: cd docusaurus && npm run verify-docs
      - name: Create issue if outdated
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'Outdated documentation detected',
              body: 'Some documentation files need review. Run `npm run verify-docs` to see details.',
              labels: ['documentation']
            })

CI/CD pipeline​

# .gitlab-ci.yml
verify-docs:
  stage: test
  script:
    - cd docusaurus
    - npm run verify-docs
  only:
    - schedules

Best practices​

  1. Set realistic thresholds - 90 days for general docs, 30 days for rapidly changing docs
  2. Review before updating - Don't just update the date; actually review the content
  3. Batch updates - Review and update multiple docs in one session
  4. Use in CI/CD - Automate checks to catch outdated docs early
  5. Document verification process - Note what you checked in commit messages

Verification checklist​

When verifying documentation:

  • Links still work (use link checker)
  • Code examples are current
  • Screenshots are up to date
  • Information is accurate
  • No outdated warnings or todos
  • New features are documented
  • Deprecated features are marked

Exit codes​

  • 0 - All docs are up to date
  • 1 - Outdated docs or errors found

Configuration​

Edit scripts/verify-docs.cjs to customize:

// Default threshold (days)
const DEFAULT_THRESHOLD = 90;

// Directories to check
const DOCS_DIR = path.join(__dirname, '../docs');
const TOOLS_SOURCE_DIR = path.join(__dirname, '../../tools');

// Directories to skip
const SKIP_DIRS = ['node_modules', 'build', '.docusaurus', 'tools'];

Thresholds by doc type​

Recommended verification thresholds:

Document typeThresholdReason
Architecture docs60 daysTech stack changes frequently
Tool documentation90 daysTools update regularly
Guides & tutorials120 daysMore stable content
API documentation30 daysCode changes frequently
README files90 daysImportant but stable

Common issues​

Wrong date format​

# ❌ Wrong
last_verified: 1/6/2026

# ✅ Correct
last_verified: 2026-01-06

Missing frontmatter​

If a file has no frontmatter, the script will report it. Use --auto-add to fix:

node scripts/verify-docs.cjs check --auto-add

File not found error​

Make sure you're in the correct directory:

cd docusaurus
npm run verify-docs

Permission errors​

Make script executable:

chmod +x docusaurus/scripts/verify-docs.cjs

JSON output format​

For CI/CD integration, use JSON output:

{
  "totalFiles": 57,
  "verified": [
    {
      "file": "docs/intro.md",
      "lastVerified": "2026-01-06",
      "daysSince": 0
    }
  ],
  "outdated": [
    {
      "file": "docs/architecture.md",
      "lastVerified": "2025-10-15",
      "daysSince": 120,
      "threshold": 90
    }
  ],
  "missing": [
    {
      "file": "docs/new-guide.md",
      "reason": "No last_verified field"
    }
  ],
  "errors": []
}

Future improvements​

Planned features:

  • Automatic verification based on git history
  • Integration with link checker (verify + check links in one command)
  • Email notifications for outdated docs
  • Dashboard for documentation health
  • Per-file custom thresholds
  • Verification history tracking