| name | basic-documentation |
| description | Documentation standards - README structure, ROADMAP patterns, skill documentation format (YAML frontmatter), markdown conventions, security documentation, API docs, and best practices. Guidelines for creating and maintaining all project documentation. Keywords: documentation, readme, roadmap, markdown, documentation-standards, yaml-frontmatter, technical-writing, api-documentation, changelog |
| last-updated | "2026-07-07T00:00:00.000Z" |
| difficulty | basic |
| tokens | ~1K |
Documentation
Standards for creating and maintaining repository documentation.
1. Core Principles (DiSCOS)
- Security First: Document security implications, auth requirements, sensitive data handling.
- Clarity: Reader's context first. Define terms on first use.
- Conciseness: Front-load key info. Tables for comparisons. Start with TL;DR.
- Certainty: "will"/"must" over "maybe"/"might". Quantify uncertainty.
- Maintenance: Documentation is code. Update with every significant change.
- Shared Defaults: Cross-package defaults and docs-sync rules belong in the repository profile or the owning source documentation. Package READMEs must stay self-contained for important facts and may reference sibling package READMEs for related guidance.
2. README.md Standard
Structure
- Header: Project Name & Badges (CI/CD, Quality Gate, License, Version)
- TL;DR: 3-5 key value propositions ("You can...")
- Navigation: Quick links to major sections
- About Project: Problem Statement, Solution Overview, Key Characteristics
- Solution Structure: Folder breakdown, component descriptions
- Getting Started: Quick setup with prerequisites
- Architecture/Design: Links to design documents
- Security: Link to security policy, vulnerability reporting
- Management: (Optional) Philosophy on Security, Task, Quality
- Footer: License, Credits
Best Practices
- Use
[ ]/[x] checklists for feature status
- Include minimal working examples
- Mention security considerations upfront
3. ROADMAP vs CHANGELOG vs RELEASE-NOTES
ROADMAP.md
Track planned features with [ ]/[/]/[x] markers, grouped by version.
CHANGELOG.md
Repository/service-level history. Reverse chronological. Sections: Added, Changed, Fixed, Security, Breaking.
RELEASE-NOTES.md
Per-package/module release notes. Use the repository profile or package metadata for the exact template, heading style, sections, prefix, and footer. Maintain versioned changes above existing history.
Update release notes when a change affects a published module's consumers or package metadata other than version-only alignment:
- Public API, contract, CLI, endpoint, event, DTO, configuration key, default, security posture, operational behavior, data/migration behavior, or observable bug fix.
- Dependency, runtime, container, or build-output changes only when they are breaking, security-relevant, consumer-visible, or alter published package artifacts.
- Published docs that are shipped as package metadata, such as package READMEs or release notes.
Do not add release-note entries for internal-only refactors, tests, comments, private/internal-only checks, agent-only docs, or routine dependency-only updates unless the repository profile declares a stricter rule.
Skip private/internal-only checks unless needed to prove public behavior or docs accuracy.
For version-aligned releases, do not add artificial version blocks to unchanged packages unless the repository profile explicitly requires them; record release notes as not required.
SemVer
- Major (X.0.0): Breaking changes
- Minor (0.X.0): New features (backward compatible)
- Patch (0.0.X): Bug fixes and security patches
4. Agent Skills Documentation
Path: .agent/skills/XX-skill-name/SKILL.md
Frontmatter (YAML)
---
name: skill-name
description: "Concise description (<100 chars) with keywords. Keywords: keyword1, keyword2"
last-updated: YYYY-MM-DD
difficulty: basic | intermediate | advanced
---
| Field | Required | Purpose |
|---|
name | Yes | Skill identifier (matches directory name) |
description | Yes | Concise summary with Keywords: suffix for semantic matching |
last-updated | Yes | Date of last meaningful content change — signals staleness |
difficulty | Yes | Triage hint: basic (orientation/reference), intermediate (domain context needed), advanced (deep framework knowledge) |
Content Sections
- Title:
# Skill Name
- Overview: Purpose and scope paragraph
- Table of Contents: Required for skills >100 lines
- Sections: Logical breakdown with tables, code blocks, examples
- Code Blocks: Runnable snippets with language specification
5. Security Documentation
Mandatory for components handling sensitive data, auth, or external communication.
Required Sections: Threat Model, Auth & Authorization, Data Protection, Vulnerability Reporting, Dependencies, Audit Trail.
6. API Documentation
REST API Pattern
### POST /api/users
Creates a new user account.
**Authentication**: Required (Bearer token)
**Request/Response**: JSON with status codes (201, 400, 401, 409)
Code API Pattern
Use XML documentation comments (<summary>, <param>, <returns>, <exception>).
7. Markdown Standards
- Headers: ATX style (
#), one # per document
- Lists: Hyphens (
-) unordered, 1. ordered
- Links: Relative paths for internal files
- Code: Always specify language
- Diagrams: Mermaid for architecture/sequence/flow — see basic-documentation-diagrams for WCAG-compliant styling
- Tables: Use for structured data, align columns
- TOC: Required for documents >100 lines
8. Code Block Best Practices
- Always specify language (
csharp, json, ```bash)
- Include necessary imports/usings
- Code should work as-is or clearly indicate placeholders
- Explain non-obvious logic with comments
9. Verification Checklist
