Documentation

Documentation Skill

When generating or updating documentation, ensure accuracy, completeness, and consistency with the codebase.

1. Public API Documentation (JSDoc / Docstrings)

• Add documentation to all public functions, methods, classes, and interfaces
• Include: purpose, parameters (with types), return value, thrown exceptions/errors
• Use the project's established doc format (JSDoc, Google-style docstrings, KDoc, Javadoc, etc.)
• Include usage examples for non-obvious APIs
• Document default values for optional parameters
• Mark deprecated APIs with @deprecated and include the migration path
• Keep doc comments concise — one sentence for simple functions, detailed for complex ones

2. README Updates

• Update the README when new features, commands, or configuration options are added
• Keep the installation/setup section current with any new dependencies or steps
• Update the usage section with new CLI commands, API endpoints, or UI features
• Maintain the project description to accurately reflect current capabilities
• Ensure badges (CI status, coverage, version) are functional and up to date
• Do NOT add sections that duplicate information available elsewhere (e.g., full API reference)

3. API Documentation

• Document all endpoints: method, path, description, parameters, request/response bodies
• Include example requests and responses with realistic data
• Document all possible error responses with HTTP status codes and error body shapes
• Document authentication requirements per endpoint
• Note rate limits, pagination parameters, and query filters
• Keep API docs versioned alongside the code — prefer generated docs (OpenAPI/Swagger) when available

4. Complex Business Logic

• Add inline comments explaining the why behind non-obvious decisions
• Document algorithms with a brief description of the approach and time/space complexity
• Explain business rules that are not self-evident from the code
• Document invariants and preconditions that callers must satisfy
• Reference external specifications, RFCs, or requirements documents by number/link

5. Changelog Maintenance

• Follow Keep a Changelog format (https://keepachangelog.com)
• Categorize entries: Added, Changed, Deprecated, Removed, Fixed, Security
• Write entries from the user's perspective, not the developer's
• Include the PR or issue number for traceability
• Keep an "Unreleased" section at the top for pending changes
• Date entries use ISO 8601 format (YYYY-MM-DD)

6. Architecture Documentation

• Update architecture docs when new services, modules, or integrations are added
• Document data flows for new features that cross service boundaries
• Keep component diagrams current (or flag them as outdated)
• Record significant design decisions as ADRs (Architecture Decision Records)

Quality Standards

• Documentation must be accurate — verify all code references, paths, and commands
• Use consistent terminology throughout (define terms in a glossary if needed)
• Write for the audience: README for new developers, API docs for consumers, inline comments for maintainers
• Run documentation links and code examples to verify they work
• Use active voice and imperative mood for instructions
• Avoid jargon without explanation; define acronyms on first use

Source: ADORSYS-GIS/cloud-identity-wallet — distributed by TomeVault.