/documentation-standard

← Back to index

Summary

Comprehensive documentation management for software projects — create, update, organize, and refactor architecture docs, ADRs, user manuals, and development guides following enforced structure, naming conventions, and content standards.

When to use

Use /documentation-standard when working with project documentation at any stage: starting from scratch, auditing existing docs for quality and consistency, refactoring structure, or reviewing docs as part of a PR or sprint. It covers directory layout, file naming, metadata headers, writing style, diagram format (Mermaid), and maintenance workflows.

Trigger phrases (from SKILL.md):

Invocation

Invoke as a slash command, optionally followed by a description of the documentation task:

/documentation-standard [description of the documentation task]

Examples of invocation targets: an existing /Documentation/ folder to audit, a new architecture doc to create, an ADR to draft, or a full doc refactor request. The skill applies its standard directory structure, naming conventions, and quality checklist to whatever target you describe.

Example 1 — Create a new architecture document

Input:

/documentation-standard Create a new architecture document for our caching strategy. Backend and infra engineers are the audience.

Output / Result:

Creating: Documentation/Architecture/170_caching_strategy.md

Metadata header added:
  Purpose: Defines caching layers and invalidation strategies
  Audience: Backend and infrastructure engineers
  Status: Draft
  Last reviewed: 2026-06-05
  Next review: 2026-09-05

Structure applied:
  ## Principles
  1. Cache close to the data source
  2. Invalidate explicitly, not by TTL
  3. Monitor cache hit rates

  ## Overview
  ...  (remaining content authored here)

Index updated: 990_documentation_index_and_contribution_guide.md

Example 2 — Audit and refactor existing documentation

Input:

/documentation-standard Audit the Documentation/ folder. We have a lot of files added over time — naming might be inconsistent, some docs may lack metadata headers, and cross-references are probably stale.

Output / Result:

Audit complete. Issues found:

Naming violations (3 files):
  - api_docs.md → rename to 600_api_reference_or_public_interface.md
  - ErrorHandling.md → rename to 140_error_handling_strategy.md
  - readme_services.md → move to Architecture/, rename to 120_services_and_integration_architecture.md

Missing metadata headers (5 files):
  - testing_strategy.md, performance.md, ... (details listed)

Broken cross-references (2 links):
  - 100_system_architecture_overview.md links to deleted services_v1.md

No duplicated content detected.
Diagrams: 2 PNG screenshots found — recommend converting to Mermaid.

Suggested actions: rename 3 files, add metadata to 5, fix 2 links, convert 2 diagrams.

Related tools