document-writing-skills（文档写作技巧）

Document Writing Skills

Purpose: This skill provides comprehensive document writing patterns, templates, and best practices that agents can apply when generating professional documentation, reports, contracts, guides, and technical writing across various domains.

When to Use Document Writing Skills

Use this skill when:

• Creating API documentation (REST/GraphQL/RPC)
• Writing technical documentation or user guides
• Generating research reports or incident reports
• Drafting architecture decision records (ADRs)
• Creating changelogs and release notes
• Writing legal memoranda or contracts
• Producing test reports or security assessments
• Authoring product requirement documents (PRDs)

Core Writing Principles

1. Clarity and Conciseness

Guidelines:

• Use active voice: "The system processes requests" (not "Requests are processed by the system")
• Use present tense: "The function returns" (not "The function will return")
• Be specific: "Response time: 200ms" (not "Response time is fast")
• Avoid jargon unless domain-appropriate
• Use short sentences (15-20 words maximum)
• Break complex ideas into numbered steps

Example - Before and After:

❌ Before: "It should be noted that the API endpoint might be utilized for the purpose of retrieving user data."
✅ After: "Use this endpoint to retrieve user data."

2. Progressive Disclosure Structure

Organize documents from high-level to detailed:

1. Summary/Overview - What and why (2-3 sentences)
2. Key Concepts - Essential understanding
3. Details - Deep-dive information
4. Reference - Complete specifications

Template:

# Document Title

## Summary
[2-3 sentences: What this is and why it matters]

## Quick Start
[Minimal steps to get started]

## Concepts
[Essential understanding]

## Detailed Guide
[In-depth information]

## Reference
[Complete specifications, API details, etc.]

3. Consistency Standards

Maintain consistency in:

• Terminology (create glossary for domain terms)
• Code formatting (use syntax highlighting)
• Section structure (follow templates)
• Date formats (ISO 8601: YYYY-MM-DD)
• Version numbers (Semantic Versioning: MAJOR.MINOR.PATCH)

Document Type Templates

API Documentation

Structure:

# API Endpoint: [Method] /path/to/endpoint

## Overview
[Brief description of what this endpoint does]

## Authentication
[Required authentication method]

## Request

**Method**: [GET/POST/PUT/DELETE]
**URL**: `/api/v1/endpoint`

**Headers**:
| Header | Value | Required |
|--------|-------|----------|
| Authorization | Bearer {token} | Yes |
| Content-Type | application/json | Yes |

**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| user_id | integer | Yes | Unique user identifier |
| limit | integer | No | Max results (default: 10) |

**Request Body** (JSON):

{ "field1": "value", "field2": 123 }

## Response

**Success Response** (200 OK):

{ "status": "success", "data": { "id": 12345, "name": "Example" } }

**Error Responses**:

| Status Code | Description | Response Body |
| --- | --- | --- |
| 400 | Bad Request | `{"error": "Invalid parameters"}` |
| 401 | Unauthorized | `{"error": "Authentication required"}` |
| 404 | Not Found | `{"error": "Resource not found"}` |
| 500 | Server Error | `{"error": "Internal server error"}` |

## Example Usage

**cURL**:

curl -X POST https://api.example.com/v1/endpoint \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"field1": "value"}'

**Python**:

import requests

response = requests.post( "https://api.example.com/v1/endpoint", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={"field1": "value"} )

## Rate Limiting

[Rate limit details if applicable]

## Notes

[Additional considerations, edge cases, deprecation warnings]

Technical Report

Structure:

# [Report Title]

**Author**: [Name/Role]
**Date**: [YYYY-MM-DD]
**Version**: [X.Y]
**Status**: [Draft/Final/Approved]

## Executive Summary
[2-3 paragraphs: Key findings, recommendations, impact]

## Background
[Context: Why this report exists, what problem it addresses]

## Methodology
[How the analysis was conducted, tools used, data sources]

## Findings

### Finding 1: [Title]
**Impact**: [High/Medium/Low]
**Evidence**: [Data, observations, metrics]
**Analysis**: [What this means]

### Finding 2: [Title]
[Same structure...]

## Recommendations

### Recommendation 1: [Action]
**Priority**: [High/Medium/Low]
**Effort**: [High/Medium/Low]
**Timeline**: [Timeframe]
**Rationale**: [Why this recommendation]

## Conclusion
[Summary of key points and next steps]

## Appendix
[Supporting data, detailed tables, raw results]

Architecture Decision Record (ADR)

Structure:

# ADR-[Number]: [Title]

**Status**: [Proposed/Accepted/Deprecated/Superseded]
**Date**: [YYYY-MM-DD]
**Deciders**: [Names/Roles]

## Context
[What is the issue we're addressing?]

## Decision
[What decision have we made?]

## Rationale
[Why did we make this decision?]

### Options Considered

#### Option 1: [Name]
**Pros**:
- [Advantage 1]
- [Advantage 2]

**Cons**:
- [Disadvantage 1]
- [Disadvantage 2]

#### Option 2: [Name]
[Same structure...]

### Decision Criteria
- [Criterion 1: Performance]
- [Criterion 2: Maintainability]
- [Criterion 3: Cost]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Neutral
- [Impact 1]

## Implementation Notes
[Guidance for implementing this decision]

## Related Decisions
- [ADR-XXX: Related decision]

## References
- [Documentation links, research papers, discussions]

User Guide

Structure:

# [Product/Feature] User Guide

## Overview
[What this is and what it helps users accomplish]

## Getting Started

### Prerequisites
- [Requirement 1]
- [Requirement 2]

### Installation
1. [Step 1 with validation]

command-to-run

**Expected output**: [What success looks like]

1. [Step 2] [Validation checkpoint]

## Tutorials

### Tutorial 1: [Basic Task]

**Goal**: [What you'll accomplish] **Time**: [Estimated duration]

**Steps**:

1. [Action]
  - **Why**: [Rationale]
  - **Validation**: [How to verify success]
2. [Next action] [Same structure...]

**Result**: [What you've achieved]

### Tutorial 2: [Advanced Task]

[Same structure...]

## Reference

### Feature 1

**Description**: [What it does] **Usage**: [How to use it] **Parameters**: [Options available] **Examples**: [Common use cases]

## Troubleshooting

### Problem: [Common issue]

**Symptoms**: [How to identify this problem] **Cause**: [Why this happens] **Solution**: [Step-by-step fix]

### Problem: [Another issue]

[Same structure...]

## FAQ

**Q: [Common question]** A: [Clear answer]

## Additional Resources

- [Link to API docs]
- [Link to community forum]

Changelog

Format: Keep a Changelog (https://keepachangelog.com/en/1.0.0/)

Structure:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- [New feature description]

### Changed
- [Change to existing functionality]

### Deprecated
- [Soon-to-be removed feature]

### Removed
- [Removed feature]

### Fixed
- [Bug fix]

### Security
- [Vulnerability fix]

## [1.2.0] - 2025-11-08

### Added
- User authentication with JWT tokens
- Password reset functionality
- Email verification

### Changed
- Improved API response times by 40%
- Updated database schema for better performance

### Fixed
- Issue #123: Login timeout on slow connections
- Memory leak in background worker

## [1.1.0] - 2025-10-15

[Previous version changes...]

## [1.0.0] - 2025-09-01

### Added
- Initial release
- User registration and login
- Basic profile management

[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/org/repo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/org/repo/releases/tag/v1.0.0

Breaking Changes Callout:

## [2.0.0] - 2025-11-08

### ⚠️ BREAKING CHANGES
- **Authentication**: Changed from session-based to JWT tokens
  - **Migration**: See [Migration Guide](./MIGRATION.md)
  - **Impact**: All clients must update authentication flow
- **API Endpoints**: Removed deprecated `/v1/users` endpoint
  - **Replacement**: Use `/v2/users` instead

Visual Elements

Code Examples

Always include:

• Syntax highlighting (specify language)
• Complete working examples (not fragments)
• Expected output
• Error handling

Template:

Complete example with imports

import requests

def get_user(user_id): """Retrieve user by ID.""" try: response = requests.get(f"https://api.example.com/users/{user_id}") response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print(f"Error: {e}") return None

Usage

user = get_user(123) print(user)

**Expected output**:

{ "id": 123, "name": "John Doe", "email": "john@example.com" }

Diagrams

When to include:

• Architecture overviews
• Data flow diagrams
• State machines
• Process workflows

Formats:

• Mermaid (for text-based diagrams in Markdown)
• ASCII art (for simple diagrams)
• Image files (for complex visuals)

Mermaid Example:

sequenceDiagram participant Client participant API participant Database

Client->>API: POST /users API->>Database: INSERT user Database-->>API: User created API-->>Client: 201 Created

Tables

Use tables for:

• Parameter specifications
• Configuration options
• Comparison matrices
• Error code listings

Best practices:

• Include headers
• Align columns consistently
• Use separators for readability
• Keep cell content concise

Domain-Specific Patterns

Legal Documents

Key requirements:

• Formal tone and precise language
• Numbered sections and subsections
• Citation formatting (jurisdiction-specific)
• Definitions section
• Signature blocks

Reference: See references/legal-document-patterns.md for:

• Contract templates
• Memorandum structure
• Citation formats (Finlex, EUR-Lex, Bluebook, etc.)
• Legal writing conventions

Security Reports

Structure:

• Executive summary with risk scores
• CVSS scoring for vulnerabilities
• STRIDE/OWASP categorization
• Remediation guidance with timelines
• Evidence and proof-of-concept

Reference: See references/security-report-patterns.md for:

• Vulnerability report template
• Threat modeling documentation
• Penetration test report structure
• Security assessment framework

Product Requirements Document (PRD)

Structure:

• Product overview and goals
• User personas and use cases
• Functional requirements
• Non-functional requirements
• Success metrics
• Release criteria

Reference: See references/prd-patterns.md for:

• Complete PRD template
• Feature prioritization frameworks (RICE, MoSCoW)
• User story formats
• Acceptance criteria patterns

Quality Checklist

Before finalizing any document, verify:

Content Quality:

• Purpose is clear in first paragraph
• All technical terms are defined or linked
• Examples are complete and tested
• No assumptions about reader knowledge
• Consistent terminology throughout

Structure Quality:

• Logical flow from high-level to detailed
• Table of contents for long documents (>5 sections)
• Clear section headings
• Appropriate use of lists vs paragraphs
• Progressive disclosure applied

Technical Quality:

• Code examples use syntax highlighting
• All code has been validated
• API endpoints include full URL
• Error codes are documented
• Links are valid and versioned

Accessibility:

• Headings use proper hierarchy (H1 > H2 > H3)
• Tables have descriptive headers
• Images have alt text
• Color is not the only indicator
• Contrast ratios meet WCAG AA standards

Metadata:

• Document has creation date (ISO 8601)
• Author/owner is identified
• Version number is specified
• Last updated date is current
• Status is indicated (Draft/Final/Deprecated)

Advanced Patterns

For detailed guidance on specialized documentation types, see:

• Legal Document Patterns: references/legal-document-patterns.md

- Contract templates (employment, service agreements, NDAs) - Legal memorandum structure - Citation formats by jurisdiction - Finnish/EU legal writing conventions

• Security Report Patterns: references/security-report-patterns.md

- Vulnerability disclosure templates - Threat modeling documentation - Penetration test report structure - CVSS scoring guidance

• Product Document Patterns: references/prd-patterns.md

- Product requirement documents (PRDs) - Feature specification templates - User story and acceptance criteria formats - Prioritization frameworks (RICE, MoSCoW, Kano)

• Technical Writing Best Practices: references/technical-writing-guide.md

- Style guide recommendations - Grammar and punctuation rules - Localization considerations - Inclusive language guidelines

Summary

This skill provides comprehensive patterns and templates for creating professional documentation across multiple domains. Apply these patterns to ensure consistency, clarity, and quality in all written deliverables.

Key Principles:

1. Clarity: Active voice, present tense, specific language
2. Structure: Progressive disclosure from high-level to detailed
3. Consistency: Templates, terminology, formatting
4. Completeness: Examples, error handling, validation
5. Quality: Verified code, tested links, proper metadata