universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/core/documentation-writing-standards.md

@@ -0,0 +1,487 @@
+# Documentation Writing Standards
+
+> **English** | [繁體中文](../locales/zh-TW/core/documentation-writing-standards.md)
+
+**Version**: 1.0.1
+**Last Updated**: 2025-12-24
+**Applicability**: All software projects (new, refactoring, migration, maintenance)
+
+---
+
+## Purpose
+
+This standard defines documentation requirements based on project types and provides detailed writing guidelines for each document category.
+
+**Relationship to Other Standards**:
+- Complements [documentation-structure.md](documentation-structure.md) which defines file organization
+- This standard focuses on **content requirements** and **project type mapping**
+
+---
+
+## Project Types and Required Documents
+
+### Document Requirements Matrix
+
+| Document | New Project | Refactoring | Migration | Maintenance | Description |
+|----------|:-----------:|:-----------:|:---------:|:-----------:|-------------|
+| **README.md** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | Project entry point |
+| **ARCHITECTURE.md** | ✅ Required | ✅ Required | ✅ Required | ⚪ Recommended | System architecture |
+| **API.md** | ⚪ If applicable | ✅ Required | ✅ Required | ⚪ Recommended | API specification |
+| **DATABASE.md** | ⚪ If applicable | ✅ Required | ✅ Required | ⚪ Recommended | Database schema |
+| **DEPLOYMENT.md** | ✅ Required | ✅ Required | ✅ Required | ⚪ Recommended | Deployment guide |
+| **MIGRATION.md** | ❌ Not needed | ✅ Required | ✅ Required | ❌ Not needed | Migration plan |
+| **ADR/** | ⚪ Recommended | ✅ Required | ✅ Required | ⚪ If applicable | Architecture decisions |
+| **CHANGELOG.md** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | Version history |
+| **CONTRIBUTING.md** | ⚪ Recommended | ⚪ Recommended | ⚪ Recommended | ⚪ If applicable | Contribution guide |
+
+**Legend**: ✅ Required | ⚪ Recommended/If applicable | ❌ Not needed
+
+---
+
+### Project Type Descriptions
+
+#### 🆕 New Project
+
+Building software from scratch.
+
+**Required Documents**:
+- README.md - Project overview, quick start
+- ARCHITECTURE.md - Design architecture (pre-development planning)
+- DEPLOYMENT.md - Deployment process
+- CHANGELOG.md - Version history
+
+**Recommended Documents**:
+- API.md - If exposing external APIs
+- DATABASE.md - If using databases
+- ADR/ - Record important technical decisions
+
+---
+
+#### 🔄 Refactoring Project
+
+Improving existing system's code structure, architecture, or technology stack without changing external behavior.
+
+**Required Documents**:
+- README.md - Update technology stack description
+- ARCHITECTURE.md - Compare old and new architecture
+- API.md - API change documentation (if applicable)
+- DATABASE.md - Schema change documentation (if applicable)
+- DEPLOYMENT.md - New deployment process
+- MIGRATION.md - Refactoring migration plan
+- ADR/ - Document refactoring decisions
+- CHANGELOG.md - Detailed change records
+
+**Key Points**:
+- MIGRATION.md must include rollback plan
+- ADR/ must document "why refactor" and "why this approach"
+
+---
+
+#### 🚚 Migration Project
+
+Moving system from one environment/platform to another (e.g., cloud migration, version upgrade).
+
+**Required Documents**:
+- README.md - New environment description
+- ARCHITECTURE.md - New architecture diagram
+- API.md - API compatibility documentation
+- DATABASE.md - Data migration documentation
+- DEPLOYMENT.md - New environment deployment
+- MIGRATION.md - Migration steps and verification
+- ADR/ - Migration decision records
+- CHANGELOG.md - Migration change records
+
+**Key Points**:
+- MIGRATION.md is the core document
+- Must include data migration verification, rollback plan, integration partner notification
+
+---
+
+#### 🔧 Maintenance Project
+
+Day-to-day maintenance, bug fixes, minor feature enhancements of existing systems.
+
+**Required Documents**:
+- README.md - Keep updated
+- CHANGELOG.md - Record every change
+
+**Recommended Documents**:
+- Other documents updated based on change scope
+
+---
+
+## Core Principles
+
+> **Documentation is an extension of code and should be treated with equal importance. Good documentation reduces communication costs, accelerates onboarding, and lowers maintenance risks.**
+
+### Documentation Pyramid
+
+```
+                    ┌─────────────┐
+                    │   README    │  ← Entry point, quick overview
+                    ├─────────────┤
+                 ┌──┴─────────────┴──┐
+                 │   ARCHITECTURE    │  ← System overview
+                 ├───────────────────┤
+              ┌──┴───────────────────┴──┐
+              │  API / DATABASE / DEPLOY │  ← Technical details
+              ├─────────────────────────┤
+           ┌──┴─────────────────────────┴──┐
+           │    ADR / MIGRATION / CHANGELOG │  ← Change history
+           └───────────────────────────────┘
+```
+
+---
+
+## Document Categories and Standards
+
+### 1. Architecture Documentation
+
+#### ARCHITECTURE.md
+
+**Purpose**: Describe overall system architecture, module division, technology choices
+
+**Required Sections**:
+
+| Section | Description | Required |
+|---------|-------------|----------|
+| System Overview | Purpose, scope, main functions | Required |
+| Architecture Diagram | Use Mermaid or ASCII Art | Required |
+| Module Description | Responsibilities, dependencies | Required |
+| Technology Stack | Frameworks, languages, database versions | Required |
+| Data Flow | Main business process data flow | Required |
+| Deployment Architecture | Production deployment topology | Recommended |
+| Design Decisions | Reasons for key decisions (or link to ADR) | Recommended |
+
+**Template Structure**:
+
+```markdown
+# System Architecture
+
+## 1. Overview
+[System purpose and scope]
+
+## 2. Architecture Diagram
+[Mermaid or ASCII diagram]
+
+## 3. Module Description
+### 3.1 Presentation Layer
+### 3.2 Business Logic Layer
+### 3.3 Data Access Layer
+
+## 4. Technology Stack
+| Category | Technology | Version |
+|----------|------------|---------|
+
+## 5. Data Flow
+[Main business process diagram]
+
+## 6. Deployment Architecture
+[Deployment topology diagram]
+```
+
+---
+
+### 2. API Documentation
+
+#### API.md
+
+**Purpose**: Document external API interfaces
+
+**Required Sections**:
+
+| Section | Description | Required |
+|---------|-------------|----------|
+| API Overview | Version, base URL, authentication | Required |
+| Authentication | Token acquisition, expiration | Required |
+| Endpoint List | All API endpoints | Required |
+| Endpoint Specifications | Request/response format for each | Required |
+| Error Code Reference | Error codes and descriptions | Required |
+| Code Examples | Examples in common languages | Recommended |
+| Rate Limiting | API call frequency limits | If applicable |
+
+**Endpoint Specification Format**:
+
+```markdown
+### POST /api/v1/resource
+
+Description of what this endpoint does.
+
+**Request**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| field1 | string | Yes | Description |
+| field2 | integer | No | Description |
+
+**Request Example**
+```json
+{
+  "field1": "value",
+  "field2": 123
+}
+```
+
+**Response**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| success | boolean | Whether successful |
+| data | object | Response data |
+
+**Response Example**
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+**Error Responses**
+| Code | Description |
+|------|-------------|
+| 400 | Bad request |
+| 401 | Unauthorized |
+```
+
+---
+
+### 3. Database Documentation
+
+#### DATABASE.md
+
+**Purpose**: Document database structure, relationships, indexing strategy
+
+**Required Sections**:
+
+| Section | Description | Required |
+|---------|-------------|----------|
+| Database Overview | Type, version, connection info | Required |
+| ER Diagram | Entity relationship diagram | Required |
+| Table List | All tables with purposes | Required |
+| Table Specifications | Column definitions for each table | Required |
+| Index Documentation | Indexing strategy and performance | Required |
+| Migration Scripts | Script locations and execution order | Required |
+| Backup Strategy | Backup frequency, retention | Recommended |
+
+**Table Specification Format**:
+
+```markdown
+### TableName
+
+Description of table purpose.
+
+**Column Definition**
+
+| Column | Data Type | Nullable | Default | Description |
+|--------|-----------|----------|---------|-------------|
+| id | bigint | No | IDENTITY | Primary key |
+| name | varchar(100) | No | - | Name field |
+| status | tinyint | No | 0 | Status flag |
+
+**Indexes**
+
+| Index Name | Columns | Type | Description |
+|------------|---------|------|-------------|
+| PK_TableName | id | CLUSTERED | Primary key |
+| IX_Status | status, created_at | NONCLUSTERED | Query optimization |
+
+**Relationships**
+
+| Related Table | Join Columns | Relationship |
+|---------------|--------------|--------------|
+| OtherTable | id = other_id | 1:N |
+```
+
+---
+
+### 4. Deployment Documentation
+
+#### DEPLOYMENT.md
+
+**Purpose**: Document deployment steps, environment configuration, troubleshooting
+
+**Required Sections**:
+
+| Section | Description | Required |
+|---------|-------------|----------|
+| Environment Requirements | Hardware, software, network | Required |
+| Installation Steps | Detailed installation process | Required |
+| Configuration | Configuration file parameters | Required |
+| Verification | How to confirm successful deployment | Required |
+| Troubleshooting | Common issues and solutions | Required |
+| Monitoring | Health checks, log locations | Recommended |
+| Scaling Guide | How to scale horizontally/vertically | If applicable |
+
+**Configuration Documentation Format**:
+
+```markdown
+### config.yaml Settings
+
+| Parameter | Default | Description | Example |
+|-----------|---------|-------------|---------|
+| db.host | localhost | Database host | `192.168.1.100` |
+| db.port | 5432 | Database port | - |
+| app.timeout | 300 | Request timeout (seconds) | - |
+```
+
+---
+
+### 5. Migration Documentation
+
+#### MIGRATION.md
+
+**Purpose**: Document migration plan, backward compatibility strategy, rollback procedures
+
+**Required Sections**:
+
+| Section | Description | Required |
+|---------|-------------|----------|
+| Migration Overview | Goals, scope, timeline | Required |
+| Prerequisites | Required preparation before migration | Required |
+| Migration Steps | Detailed migration process | Required |
+| Verification Checklist | Post-migration verification items | Required |
+| Rollback Plan | Steps to rollback on failure | Required |
+| Backward Compatibility | API/database compatibility notes | Required |
+| Integration Partner Notification | External systems to notify | If applicable |
+
+---
+
+### 6. Architecture Decision Records (ADR)
+
+#### docs/ADR/NNN-title.md
+
+**Purpose**: Record important architectural decisions and their rationale
+
+**File Naming**: `NNN-kebab-case-title.md` (e.g., `001-use-postgresql.md`)
+
+**Required Sections**:
+
+| Section | Description | Required |
+|---------|-------------|----------|
+| Title | Decision name | Required |
+| Status | proposed/accepted/deprecated/superseded | Required |
+| Context | Why this decision is needed | Required |
+| Decision | Specific decision content | Required |
+| Consequences | Impact of decision (positive/negative) | Required |
+| Alternatives | Other options considered | Recommended |
+
+**Template**:
+
+```markdown
+# ADR-001: [Decision Title]
+
+## Status
+Accepted
+
+## Context
+[Why this decision is needed...]
+
+## Decision
+[Specific decision...]
+
+## Consequences
+
+### Positive
+- Benefit 1
+- Benefit 2
+
+### Negative
+- Drawback 1
+- Drawback 2
+
+## Alternatives Considered
+1. Alternative A - Rejected because...
+2. Alternative B - Rejected because...
+```
+
+---
+
+## Quality Standards
+
+### Format Requirements
+
+| Item | Standard |
+|------|----------|
+| Language | English |
+| Encoding | UTF-8 |
+| Line Length | Recommended ≤ 120 characters |
+| Diagrams | Prefer Mermaid, then ASCII Art |
+| Links | Use relative paths for internal links |
+
+### Maintenance Requirements
+
+| Item | Standard |
+|------|----------|
+| Sync Updates | Update docs when code changes |
+| Version Marking | Mark version and update date at top |
+| Review Inclusion | Include doc changes in code review |
+| Periodic Review | Review docs quarterly for staleness |
+
+### Review Checklist
+
+Before submitting documentation:
+
+- [ ] Required sections complete
+- [ ] No outdated or incorrect information
+- [ ] All links working
+- [ ] Examples are executable/accurate
+- [ ] Format follows standards
+
+---
+
+## File Location Standards
+
+```
+project-root/
+├── README.md                    # Project entry document
+├── CONTRIBUTING.md              # Contribution guide
+├── CHANGELOG.md                 # Change log
+├── .standards/ or .claude/      # Development standards
+│   ├── documentation-writing-standards.md
+│   └── ...
+└── 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
+    ├── ADR/                     # Architecture decision records
+    │   ├── 001-xxx.md
+    │   └── ...
+    └── DB/                      # Database scripts
+```
+
+---
+
+## Recommended Tools
+
+| Purpose | Tools |
+|---------|-------|
+| Markdown Editing | VS Code + Markdown Preview Enhanced |
+| Diagram Drawing | Mermaid / draw.io / PlantUML |
+| API Documentation | OpenAPI (Swagger) / Redoc |
+| ER Diagram | dbdiagram.io / DBeaver |
+
+---
+
+## Related Standards
+
+- [Documentation Structure Standard](documentation-structure.md)
+- [Changelog Standards](changelog-standards.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.1 | 2025-12-24 | Added: Related Standards section |
+| 1.0.0 | 2025-12-10 | Initial documentation writing standards |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).