--- name: doc-validation-rfc-37 description: > Validate documentation structure, freshness, and RFC-37 compliance using bitso-documentation-linter. Ensures docs/ folder structure (api, decisions, concepts, how-tos, runbooks) and Confluence mirroring metadata. Use when validating documentation or checking for sync issues. compatibility: All repositories with docs/ folder; requires bitso-documentation-linter metadata: version: "1.0.0" rfc: "RFC-37" linter: "bitso-documentation-linter" --- # RFC-37 Documentation Validation Validates documentation structure and synchronization following [RFC-37](https://bitsomx.atlassian.net/wiki/spaces/BAB/pages/4485840987/RFC-37+Service+documentation+standardization) standards. ## When to use this skill - Validating documentation structure against RFC-37 - Checking if documentation is synchronized with code - Running documentation linting before commits - Setting up documentation validation in CI/CD - Fixing documentation linting violations - Verifying Confluence mirroring configuration ## Skill Contents ### Sections - [When to use this skill](#when-to-use-this-skill) (L19-L27) - [Quick Start](#quick-start) (L67-L106) - [Standard Directory Structure](#standard-directory-structure) (L107-L123) - [Documentation Validation Checks](#documentation-validation-checks) (L124-L135) - [Pre-Push Documentation Check](#pre-push-documentation-check) (L136-L175) - [Available Functions](#available-functions) (L176-L203) - [Documentation Tools by Project Type](#documentation-tools-by-project-type) (L204-L212) - [Best Practices](#best-practices) (L213-L234) - [References](#references) (L235-L244) - [Assets](#assets) (L245-L252) - [Related Skills](#related-skills) (L253-L259) ### Available Resources **📚 references/** - Detailed documentation - [ai fixes](references/ai-fixes.md) - [confluence metadata](references/confluence-metadata.md) - [go](references/go) - [installation](references/installation.md) - [java](references/java) - [python](references/python) - [rfc 37](references/rfc-37.md) - [typescript](references/typescript) - [validation rules](references/validation-rules.md) **🔧 scripts/** - Automation scripts - [check docs updated](scripts/check-docs-updated.ts) **📦 assets/** - Templates and resources - [doclinterrc.yml.template](assets/doclinterrc.yml.template) - [local-execution.md.template](assets/local-execution.md.template) - [mark.toml.template](assets/mark.toml.template) --- ## Quick Start ### 1. Install the linter ```bash brew tap bitsoex/homebrew-bitso brew install bitso-documentation-linter ``` See [references/installation.md](references/installation.md) for alternative installation methods. ### 2. Create directory structure ```bash mkdir -p docs/{decisions,how-tos,runbooks} mkdir -p docs/my-service/{concepts,getting-started} ``` ### 3. Create Confluence config ```bash # Copy and edit the template cp assets/mark.toml.template docs/mark.toml ``` See [references/confluence-metadata.md](references/confluence-metadata.md) for configuration details. ### 4. Run validation ```bash # Basic validation doclinter --repo-path . --verbose # Preview Confluence tree doclinter tree --repo-path . # Via skills CLI node .scripts/skills-cli.ts doc-validation-rfc-37 validate ``` ## Standard Directory Structure ``` docs/ ├── api/ # API documentation │ ├── async/ # Event-driven APIs │ ├── grpc/ # gRPC APIs │ └── rest/ # REST APIs ├── decisions/ # Architecture Decision Records (required) ├── how-tos/ # Step-by-step guides (required) │ └── local-execution.md # REQUIRED for all services ├── runbooks/ # Operational procedures (required) └── / # Service-specific docs ├── concepts/ # Architecture, design (required) └── getting-started/ # Quick start (required) ``` ## Documentation Validation Checks | Check | What It Does | Severity | |-------|-------------|----------| | **README presence** | Verifies README.md exists | Error | | **Broken links** | Checks internal Markdown links | Warning | | **API docs** | Looks for generated API documentation | Info | | **Freshness** | Compares doc timestamps to code | Warning | | **RFC-37 structure** | Validates `docs/` folder structure | Error | | **Confluence metadata** | Validates mark.toml and parent IDs | Error | | **Local execution** | Checks for required local-execution.md | Error | ## Pre-Push Documentation Check The system verifies documentation is updated when significant files change. ### Architecture Files That Trigger Doc Checks ```javascript const ARCHITECTURE_FILES = [ 'technology-hierarchy.json', 'repo-overrides.json', 'managed-paths.json', '.scripts/convert-rules.ts', '.scripts/targeting.ts', '.scripts/safe-sync.ts', '.scripts/ci-distribute.ts', '.github/workflows/ci.yaml' ]; ``` ### Expected Documentation Updates When architecture files change, update one of: - `docs/ai-ide-management/concepts/architecture.md` - `docs/ai-ide-management/how-tos/targeting-and-inheritance.md` - `docs/ai-ide-management/overview.md` - `README.md` ### Skipping the Check ```bash # For a single commit (when docs truly aren't needed) AI_AGENTS_SKIP_DOCS_CHECK=1 git commit -m "chore: minor config tweak" # Or document why in commit message git commit -m "fix: typo in config No docs update needed - cosmetic change only" ``` ## Available Functions ### Via Skills CLI ```bash node .scripts/skills-cli.ts doc-validation-rfc-37 validate node .scripts/skills-cli.ts doc-validation-rfc-37 lint ``` ### Programmatic Usage ```javascript import { validateDocs, // Run all documentation checks checkReadme, // Verify README presence checkBrokenLinks, // Find broken internal links checkApiDocs, // Look for API documentation checkFreshness, // Compare doc/code timestamps DOC_TOOLS // Recommended tools by project type } from './.scripts/lib/skills/doc-sync.ts'; const result = await validateDocs('.', { quiet: false }); console.log('Passed:', result.passed); console.log('Issues:', result.issues); console.log('Warnings:', result.warnings); ``` ## Documentation Tools by Project Type | Project | Tools | Commands | |---------|-------|----------| | **Java/Gradle** | Javadoc, Checkstyle | `./gradlew javadoc` | | **Node.js** | TypeDoc, JSDoc, markdownlint | `npx typedoc`, `npx markdownlint "**/*.md"` | | **Python** | Sphinx, pydocstyle, MkDocs | `sphinx-build`, `pydocstyle` | | **Go** | godoc, go doc | `go doc -all` | ## Best Practices ### 1. Document As You Code - Update docs in the same PR as code changes - Use the pre-push hook to catch missing updates - Keep README.md as the single source of truth ### 2. Structure Documentation Follow RFC-37 structure for consistency (see directory structure above). ### 3. Link Related Docs Use relative links between documentation files. ### 4. Keep Docs Fresh - Run freshness checks periodically - Update docs when APIs change - Review docs during code reviews ## References | Reference | Description | |-----------|-------------| | [references/rfc-37.md](references/rfc-37.md) | RFC-37 summary and requirements | | [references/validation-rules.md](references/validation-rules.md) | All 10 linter rules with examples | | [references/confluence-metadata.md](references/confluence-metadata.md) | Confluence config (mark.toml, metadata) | | [references/installation.md](references/installation.md) | Linter installation guide | | [references/ai-fixes.md](references/ai-fixes.md) | AI-assisted documentation fixes | ## Assets | Asset | Description | |-------|-------------| | [assets/mark.toml.template](assets/mark.toml.template) | Confluence config template | | [assets/doclinterrc.yml.template](assets/doclinterrc.yml.template) | Linter config template | | [assets/local-execution.md.template](assets/local-execution.md.template) | Local execution doc template | ## Related Skills | Skill | Purpose | |-------|---------| | [doc-generation-rfc-37](.claude/skills/doc-generation-rfc-37/SKILL.md) | AI-assisted documentation generation | | [quality-checks](.claude/skills/quality-checks/SKILL.md) | Quality gate orchestration | | [git-hooks](.claude/skills/git-hooks/SKILL.md) | Pre-commit/pre-push hook setup |