gh-jschulte-claude-plugins-stackshift/skills/analyze/operations/documentation-scan.md

Documentation Scan

Scan for existing documentation and assess quality.

Overview

Identify all existing documentation to understand:

• What's already documented
• Quality and completeness of docs
• What documentation is missing
• Where docs are located

---

Documentation Discovery

Find Documentation Directories

# Common documentation directories
ls -la docs/ 2>/dev/null
ls -la documentation/ 2>/dev/null
ls -la doc/ 2>/dev/null
ls -la wiki/ 2>/dev/null
ls -la .docs/ 2>/dev/null

Find Markdown Files

# Find all markdown files (limiting to avoid noise)
find . -type f -name "*.md" \
  | grep -v -E "node_modules|vendor|\.git|dist|build" \
  | head -30

Common Documentation Files

Look for these standard files:

# Standard docs
ls -la README.md 2>/dev/null
ls -la CONTRIBUTING.md 2>/dev/null
ls -la CHANGELOG.md 2>/dev/null
ls -la LICENSE 2>/dev/null
ls -la CODE_OF_CONDUCT.md 2>/dev/null
ls -la SECURITY.md 2>/dev/null

# Setup/deployment docs
ls -la INSTALL.md 2>/dev/null
ls -la DEPLOYMENT.md 2>/dev/null
ls -la SETUP.md 2>/dev/null

# Architecture docs
ls -la ARCHITECTURE.md 2>/dev/null
ls -la DESIGN.md 2>/dev/null
ls -la API.md 2>/dev/null

---

Documentation Categories

README Assessment

Read README.md and assess quality:

Good README includes:

• Clear project description
• Installation/setup instructions
• Usage examples
• API documentation or links
• Development guide
• Testing instructions
• Deployment guide
• Contributing guidelines
• License information

Rate as:

• Good - Comprehensive, well-organized, covers all key areas
• Basic - Has description and setup, but missing key sections
• Poor - Minimal info, outdated, or confusing

API Documentation

Look for API documentation:

# OpenAPI/Swagger
find . -name "openapi.yaml" -o -name "openapi.yml" -o -name "swagger.yaml" -o -name "swagger.json" 2>/dev/null

# API doc generators
find . -name "apidoc.json" -o -name ".redocly.yaml" 2>/dev/null

# API docs directories
ls -la docs/api/ 2>/dev/null
ls -la api-docs/ 2>/dev/null

Assessment:

• Yes - OpenAPI spec or comprehensive API docs exist
• Partial - Some API docs but incomplete
• No - No API documentation found

Architecture Documentation

Look for architecture diagrams and docs:

# Architecture docs
find . -name "ARCHITECTURE.md" -o -name "architecture.md" -o -name "DESIGN.md" 2>/dev/null

# Diagram files
find . \( -name "*.drawio" -o -name "*.mermaid" -o -name "*.puml" -o -name "*.svg" \) \
  | grep -i "architecture\|diagram\|flow" 2>/dev/null

Assessment:

• Yes - Architecture docs with diagrams/explanations
• Partial - Some architecture info in README
• No - No architecture documentation

Setup/Deployment Documentation

# Deployment docs
find . -name "DEPLOYMENT.md" -o -name "deployment.md" -o -name "DEPLOY.md" 2>/dev/null

# Infrastructure docs
ls -la infrastructure/README.md 2>/dev/null
ls -la terraform/README.md 2>/dev/null
ls -la .github/workflows/ 2>/dev/null

Assessment:

• Yes - Clear deployment and infrastructure docs
• Partial - Basic setup but missing details
• No - No deployment documentation

Developer Documentation

# Developer guides
find . -name "CONTRIBUTING.md" -o -name "DEVELOPMENT.md" -o -name "dev-guide.md" 2>/dev/null

# Code comments/JSDoc
grep -r "@param\|@returns\|@description" src/ 2>/dev/null | wc -l

Assessment:

• Yes - Developer guide with setup, conventions, workflow
• Partial - Some developer info scattered
• No - No developer documentation

Testing Documentation

# Test docs
find . -name "TESTING.md" -o -name "test-guide.md" 2>/dev/null

# Test README files
find . -path "*/tests/README.md" -o -path "*/test/README.md" 2>/dev/null

Assessment:

• Yes - Testing guide with examples and conventions
• Partial - Basic test info in README
• No - No testing documentation

Database Documentation

# Database docs
find . -name "schema.md" -o -name "database.md" -o -name "DATA_MODEL.md" 2>/dev/null

# ER diagrams
find . -name "*er-diagram*" -o -name "*schema-diagram*" 2>/dev/null

# Migration docs
ls -la migrations/README.md 2>/dev/null
ls -la prisma/README.md 2>/dev/null

Assessment:

• Yes - Database schema docs and ER diagrams
• Partial - Schema file but no explanatory docs
• No - No database documentation

---

Documentation Tools Detection

Identify if automated documentation tools are configured:

Code Documentation Generators

# JSDoc/TypeDoc (JavaScript/TypeScript)
grep -r "typedoc\|jsdoc" package.json 2>/dev/null

# Sphinx (Python)
ls -la docs/conf.py 2>/dev/null

# Javadoc (Java)
grep -r "javadoc" pom.xml build.gradle 2>/dev/null

# RDoc/YARD (Ruby)
ls -la .yardopts 2>/dev/null

# Doxygen (C/C++)
ls -la Doxyfile 2>/dev/null

API Documentation Tools

# Swagger UI
grep -r "swagger-ui" package.json 2>/dev/null

# Redoc
grep -r "redoc" package.json 2>/dev/null

# Postman collections
find . -name "*.postman_collection.json" 2>/dev/null

Static Site Generators

# Docusaurus
grep -r "docusaurus" package.json 2>/dev/null
ls -la docusaurus.config.js 2>/dev/null

# VuePress
grep -r "vuepress" package.json 2>/dev/null

# MkDocs
ls -la mkdocs.yml 2>/dev/null

# GitBook
ls -la .gitbook.yaml 2>/dev/null

# Mintlify
ls -la mint.json 2>/dev/null

---

Documentation Quality Checklist

For each category, assess:

• Exists - Documentation files are present
• Current - Docs match current code (check dates)
• Complete - Covers all major features/components
• Clear - Well-written and easy to understand
• Examples - Includes code examples and usage
• Maintained - Recently updated (check git log)

---

Output Summary

Summarize findings:

## Existing Documentation

### README.md
- **Status:** Yes
- **Quality:** Good
- **Coverage:** Installation, usage, API overview, development setup
- **Last Updated:** 2024-01-15
- **Notes:** Comprehensive but missing deployment section

### API Documentation
- **Status:** Partial
- **Type:** Inline JSDoc comments only
- **Coverage:** ~60% of endpoints documented
- **OpenAPI Spec:** No
- **Notes:** Should generate OpenAPI spec

### Architecture Documentation
- **Status:** No
- **Notes:** Architecture decisions are scattered in code comments

### Setup/Deployment Documentation
- **Status:** Yes
- **Files:** DEPLOYMENT.md, infrastructure/README.md
- **Coverage:** AWS deployment, CI/CD, environment setup
- **Quality:** Basic

### Developer Documentation
- **Status:** Partial
- **Files:** CONTRIBUTING.md
- **Coverage:** PR process, code style guide
- **Missing:** Local development setup, debugging guide

### Testing Documentation
- **Status:** No
- **Notes:** No testing guide, test structure undocumented

### Database Documentation
- **Status:** Yes
- **Type:** Prisma schema file with comments
- **Coverage:** All models documented inline
- **ER Diagram:** No
- **Notes:** Should generate ER diagram from schema

### Documentation Tools
- **Configured:** None
- **Recommended:** TypeDoc for code docs, Swagger for API docs

---

Missing Documentation Identification

List what documentation should be created:

Critical (needed for Step 2):

• OpenAPI specification for API endpoints
• Architecture overview document
• Database ER diagram

Important (create during specification):

• Comprehensive testing guide
• Deployment runbook
• Troubleshooting guide

Nice-to-have:

• Code contribution guide
• ADRs (Architecture Decision Records)
• Security documentation

---

Documentation Metrics

Calculate documentation coverage:

# Count documented vs undocumented functions (example for JS/TS)
# Total functions
grep -r "function\|const.*=>.*{" src/ | wc -l

# Documented functions (with JSDoc)
grep -B1 "function\|const.*=>" src/ | grep -c "/\*\*"

# Calculate percentage

Report as:

• Code documentation coverage: ~45% (estimated)
• API endpoint documentation: ~60%
• Feature documentation: ~30%
• Overall documentation score: 4/10

---

Notes

• Check git history to see when docs were last updated
• Compare doc dates with code changes to identify stale docs
• Look for TODO/FIXME comments in docs indicating incomplete sections
• Verify links in docs aren't broken