| 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 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
Available Resources
📚 references/ - Detailed documentation
🔧 scripts/ - Automation scripts
📦 assets/ - Templates and resources
Quick Start
1. Install the linter
brew tap bitsoex/homebrew-bitso
brew install bitso-documentation-linter
See references/installation.md for alternative installation methods.
2. Create directory structure
mkdir -p docs/{decisions,how-tos,runbooks}
mkdir -p docs/my-service/{concepts,getting-started}
3. Create Confluence config
cp assets/mark.toml.template docs/mark.toml
See references/confluence-metadata.md for configuration details.
4. Run validation
doclinter --repo-path . --verbose
doclinter tree --repo-path .
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-name>/ # 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
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.mddocs/ai-ide-management/how-tos/targeting-and-inheritance.mddocs/ai-ide-management/overview.mdREADME.md
Skipping the Check
AI_AGENTS_SKIP_DOCS_CHECK=1 git commit -m "chore: minor config tweak"
git commit -m "fix: typo in config
No docs update needed - cosmetic change only"
Available Functions
Via Skills CLI
node .scripts/skills-cli.ts doc-validation-rfc-37 validate
node .scripts/skills-cli.ts doc-validation-rfc-37 lint
Programmatic Usage
import {
validateDocs,
checkReadme,
checkBrokenLinks,
checkApiDocs,
checkFreshness,
DOC_TOOLS
} 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
Assets
Related Skills
