ValorVie Documentation Guide
Language: English | 繁體中文
Version: 2.1.0 Last Updated: 2026-03-17 Applicability: Claude Code Skills
Purpose
This skill provides comprehensive guidance on project documentation, including:
- Documentation structure and file organization
- Content requirements by project type
- Writing standards for technical documents
- Templates for common documentation types
Quick Reference (YAML Compressed)
# === PROJECT TYPE → DOCUMENT REQUIREMENTS ===
document_matrix:
# README ARCH API DB DEPLOY MIGRATE ADR CHANGE CONTRIB
new: [REQ, REQ, if_app, if_app, REQ, NO, REC, REQ, REC]
refactor: [REQ, REQ, REQ, REQ, REQ, REQ, REQ, REQ, REC]
migration: [REQ, REQ, REQ, REQ, REQ, REQ, REQ, REQ, REC]
maintenance:[REQ, REC, REC, REC, REC, NO, if_app, REQ, if_app]
# REQ=Required, REC=Recommended, if_app=If applicable, NO=Not needed
# === DOCUMENTATION PYRAMID ===
pyramid:
level_1: "README.md → Entry point, quick overview"
level_2: "ARCHITECTURE.md → System overview"
level_3: "API.md, DATABASE.md, DEPLOYMENT.md → Technical details"
level_4: "ADR/, MIGRATION.md, CHANGELOG.md → Change history"
# === ESSENTIAL FILES ===
root_files:
README.md: {required: true, purpose: "Project overview, quick start"}
CONTRIBUTING.md: {required: "recommended", purpose: "Contribution guidelines"}
CHANGELOG.md: {required: "recommended", purpose: "Version history"}
LICENSE: {required: "for OSS", purpose: "License information"}
docs_structure:
INDEX.md: "Documentation index"
ARCHITECTURE.md: "System architecture"
API.md: "API documentation"
DATABASE.md: "Database schema"
DEPLOYMENT.md: "Deployment guide"
MIGRATION.md: "Migration plan (if applicable)"
ADR/: "Architecture Decision Records"
# === FILE NAMING ===
naming:
root: "UPPERCASE.md (README.md, CONTRIBUTING.md, CHANGELOG.md)"
docs: "lowercase-kebab-case.md (getting-started.md, api-reference.md)"
# === QUALITY STANDARDS ===
quality:
format:
language: "English (or project-specified)"
encoding: "UTF-8"
line_length: "≤120 characters recommended"
diagrams: "Mermaid preferred, then ASCII Art"
links: "Relative paths for internal links"
maintenance:
sync: "Update docs when code changes"
version: "Mark version and date at top"
review: "Include docs in code review"
periodic: "Review quarterly for staleness"
# === DIÁTAXIS CLASSIFICATION ===
diataxis:
tutorial: "Learning-oriented (getting-started.md)"
how_to: "Task-oriented (deployment.md, migration.md)"
reference: "Information-oriented (api-reference.md, CHANGELOG.md)"
explanation: "Understanding-oriented (architecture.md, ADR/)"
header: "Add **Document Type**: Tutorial | How-to | Reference | Explanation"
# === LLM DISCOVERY ===
llm_discovery:
llms_txt: "Structured index at project root for LLM retrieval"
llms_full_txt: "Optional full concatenated docs"
when: "Public projects, public APIs, projects using AI tools"
# === QUALITY METRICS ===
quality_metrics:
leading: ["Coverage ≥90%", "Freshness ≤90d", "Link Health 100%", "Example Validity 100%"]
lagging: ["Support ticket reduction", "Onboarding time", "Doc-related PR comments"]
tools: [markdown-link-check, lychee, remark-lint, vale, textstat]
# === ADR ENHANCED ===
adr_enhanced:
new_fields: [Date, Deciders, Drivers, "supersedes/superseded-by"]
lifecycle: "proposed → accepted → [deprecated | superseded]"
decision_matrix: "impact × reversibility → ADR required?"
# === TRANSLATION-FRIENDLY ===
translation_friendly:
rules: ["Complete sentences", "No idioms", "Consistent terminology", "Simple SVO", "Explicit references"]
glossary: "Maintain glossary.md for term consistency"
status_tracking: "YAML frontmatter with translation_status, source_version"
Project Type Document Requirements
Document Requirements Matrix
| Document | New Project | Refactoring | Migration | Maintenance |
|---|---|---|---|---|
| README.md | ✅ Required | ✅ Required | ✅ Required | ✅ Required |
| ARCHITECTURE.md | ✅ Required | ✅ Required | ✅ Required | ⚪ Recommended |
| API.md | ⚪ If applicable | ✅ Required | ✅ Required | ⚪ Recommended |
| DATABASE.md | ⚪ If applicable | ✅ Required | ✅ Required | ⚪ Recommended |
| DEPLOYMENT.md | ✅ Required | ✅ Required | ✅ Required | ⚪ Recommended |
| MIGRATION.md | ❌ Not needed | ✅ Required | ✅ Required | ❌ Not needed |
| ADR/ | ⚪ Recommended | ✅ Required | ✅ Required | ⚪ If applicable |
| CHANGELOG.md | ✅ Required | ✅ Required | ✅ Required | ✅ Required |
Project Type Quick Reference
🆕 New Project → README + ARCHITECTURE + DEPLOYMENT + CHANGELOG
🔄 Refactoring → All documents + MIGRATION + ADR (document "why refactor")
🚚 Migration → All documents + MIGRATION (core document) + data verification
🔧 Maintenance → README + CHANGELOG (update based on change scope)
Documentation Pyramid
┌─────────────┐
│ README │ ← Entry point, quick overview
├─────────────┤
┌──┴─────────────┴──┐
│ ARCHITECTURE │ ← System overview
├───────────────────┤
┌──┴───────────────────┴──┐
│ API / DATABASE / DEPLOY │ ← Technical details
├─────────────────────────┤
┌──┴─────────────────────────┴──┐
│ ADR / MIGRATION / CHANGELOG │ ← Change history
└───────────────────────────────┘
Document Templates (YAML Compressed)
# === README.md ===
readme:
minimum:
- "# Project Name"
- "Brief one-liner description"
- "## Installation"
- "## Usage"
- "## License"
recommended:
- "# Project Name + Badges"
- "## Features (bullet list)"
- "## Installation"
- "## Quick Start / Usage"
- "## Documentation (link to docs/)"
- "## Contributing (link to CONTRIBUTING.md)"
- "## License"
# === ARCHITECTURE.md ===
architecture:
required:
- system_overview: "Purpose, scope, main functions"
- architecture_diagram: "Mermaid or ASCII Art"
- module_description: "Responsibilities, dependencies"
- technology_stack: "Frameworks, languages, versions"
- data_flow: "Main business process"
recommended:
- deployment_architecture: "Production topology"
- design_decisions: "Key decisions (or link to ADR)"
# === API.md ===
api:
required:
- api_overview: "Version, base URL, authentication"
- authentication: "Token acquisition, expiration"
- endpoint_list: "All API endpoints"
- endpoint_specs: "Request/response format"
- error_codes: "Error codes and descriptions"
recommended:
- code_examples: "Examples in common languages"
- rate_limiting: "API call frequency limits"
endpoint_format: |
### POST /api/v1/resource
**Request**: | Field | Type | Required | Description |
**Response**: | Field | Type | Description |
**Errors**: | Code | Description |
# === DATABASE.md ===
database:
required:
- db_overview: "Type, version, connection info"
- er_diagram: "Entity relationship diagram"
- table_list: "All tables with purposes"
- table_specs: "Column definitions"
- index_docs: "Indexing strategy"
- migration_scripts: "Script locations"
recommended:
- backup_strategy: "Frequency, retention"
table_format: |
### TableName
**Columns**: | Column | Type | Nullable | Default | Description |
**Indexes**: | Name | Columns | Type |
**Relations**: | Related | Join | Relationship |
# === DEPLOYMENT.md ===
deployment:
required:
- environment_requirements: "Hardware, software, network"
- installation_steps: "Detailed process"
- configuration: "Config file parameters"
- verification: "Confirm successful deployment"
- troubleshooting: "Common issues and solutions"
recommended:
- monitoring: "Health checks, log locations"
- scaling_guide: "Horizontal/vertical scaling"
# === MIGRATION.md ===
migration:
required:
- overview: "Goals, scope, timeline"
- prerequisites: "Required preparation"
- migration_steps: "Detailed process"
- verification_checklist: "Post-migration checks"
- rollback_plan: "Steps on failure"
- backward_compatibility: "API/DB compatibility"
recommended:
- partner_notification: "External systems to notify"
# === ADR (Architecture Decision Record) ===
adr:
filename: "NNN-kebab-case-title.md (e.g., 001-use-postgresql.md)"
required:
- title: "Decision name"
- status: "proposed | accepted | deprecated | superseded"
- context: "Why this decision is needed"
- decision: "Specific decision content"
- consequences: "Impact (positive/negative)"
recommended:
- alternatives: "Other options considered"
File Location Standards
project-root/
├── README.md # Project entry document
├── CONTRIBUTING.md # Contribution guide
├── CHANGELOG.md # Change log
├── LICENSE # License file
└── docs/ # Documentation directory
├── INDEX.md # Documentation index
├── ARCHITECTURE.md # Architecture document
├── API.md # API document
├── DATABASE.md # Database document
├── DEPLOYMENT.md # Deployment document
├── MIGRATION.md # Migration document (if needed)
└── ADR/ # Architecture decision records
├── 001-xxx.md
└── ...
README.md Required Sections
Minimum Viable README
# Project Name
Brief one-liner description.
## Installation
```bash
npm install your-package
Usage
const lib = require('your-package');
lib.doSomething();
License
MIT
### Recommended README Sections
1. **Project Name & Description**
2. **Badges** (CI status, coverage, npm version)
3. **Features** (bullet list)
4. **Installation**
5. **Quick Start / Usage**
6. **Documentation** (link to docs/)
7. **Contributing** (link to CONTRIBUTING.md)
8. **License**
---
## ADR Template
```markdown
# ADR-001: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded
**Deciders**: [List of people involved]
**Supersedes**: ADR-NNN (if applicable)
**Superseded by**: ADR-NNN (if applicable)
## Drivers
- [Key factor 1]
- [Key factor 2]
## Context
[Why this decision is needed...]
## Decision
[Specific decision...]
## Consequences
### Positive
- Benefit 1
- Benefit 2
### Negative
- Drawback 1
- Drawback 2
## Alternatives Considered
### Alternative A: [Name]
- **Pros**: ...
- **Cons**: ...
- **Rejected because**: ...
When to write ADR (impact × reversibility):
- High impact + Hard to reverse → ADR required
- High impact + Easy to reverse → Optional
- Low impact + Hard to reverse → Optional
- Low impact + Easy to reverse → No ADR needed
Documentation Audit Checklist
When reviewing a project's documentation:
□ README.md exists with essential sections
□ Installation instructions are clear and tested
□ Usage examples are provided and work
□ License specified
□ ARCHITECTURE.md exists (for non-trivial projects)
□ API.md exists (if APIs exposed)
□ DATABASE.md exists (if databases used)
□ DEPLOYMENT.md exists (for deployed projects)
□ ADR/ exists for major decisions
□ CHANGELOG.md follows Keep a Changelog format
□ All internal links working
□ Diagrams are up to date
□ No outdated information
Configuration Detection
Detection Order
- Check
CONTRIBUTING.mdfor "Disabled Skills" section - Check
CONTRIBUTING.mdfor "Documentation Language" section - Check existing documentation structure
- If not found, default to English
First-Time Setup
If documentation is missing:
- Ask: "This project doesn't have complete documentation. Which language should I use? (English / 中文)"
- Determine project type (new/refactor/migrate/maintain)
- Create required documents based on matrix
- Suggest documenting in
CONTRIBUTING.md:
## Documentation Standards
### Language
This project uses **English** for documentation.
### Required Documents
Based on project type, we maintain:
- README.md
- ARCHITECTURE.md
- DEPLOYMENT.md
- CHANGELOG.md
Detailed Guidelines
For complete standards, see:
Next Steps Guidance | 下一步引導
After /docs-guide completes, the AI assistant should suggest:
文件結構與需求已釐清。建議下一步 / Documentation structure and requirements clarified. Suggested next steps:
- 執行
/docs根據指南直接產生專案文件 ⭐ Recommended / 推薦 — 立即將文件指南化為行動 / Turn documentation guidelines into action immediately- 執行
/changelog建立或更新 CHANGELOG.md — 確保變更歷史完整 / Ensure change history is complete- 執行
/sdd將文件需求納入規格驅動開發 — 確保文件與功能同步 / Ensure docs stay in sync with features
Related Standards
- Documentation Writing Standards - Content requirements
- Documentation Structure - File organization
- Changelog Standards - CHANGELOG format
- Changelog Guide Skill - CHANGELOG skill
Version History
| Version | Date | Changes |
|---|---|---|
| 2.1.0 | 2026-03-17 | Added: Diátaxis classification, LLM discovery, quality metrics, enhanced ADR template, translation-friendly writing |
| 2.0.0 | 2026-01-12 | Added: Project type matrix, document templates, documentation pyramid |
| 1.0.0 | 2025-12-24 | Initial release |
License
This skill is released under CC BY 4.0.
Source: universal-dev-standards