菜单
Technical writing best practices including documentation structure, clear writing principles, API documentation, tutorials, changelogs, and markdown formatting. Use when writing documentation, creating READMEs, documenting APIs, or writing tutorials.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
REST API design patterns, OpenAPI specifications, versioning strategies, authentication, error handling, and security best practices. Use when designing APIs, creating endpoints, documenting APIs, or implementing backend services that expose HTTP APIs.
Code quality standards including SOLID principles, design patterns, code smells, refactoring techniques, naming conventions, and technical debt management. Use when reviewing code, refactoring, ensuring quality, or detecting code smells.
Scientific debugging methodology including hypothesis-driven debugging, bug reproduction, binary search debugging, stack trace analysis, logging strategies, and root cause analysis. Use when debugging errors, analyzing stack traces, investigating bugs, or troubleshooting performance issues.
DevOps patterns including CI/CD pipeline design, GitHub Actions, Infrastructure as Code, Docker, Kubernetes, deployment strategies, monitoring, and disaster recovery. Use when setting up CI/CD, deploying applications, managing infrastructure, or creating pipelines.
Modern frontend architecture patterns for React, Next.js, and TypeScript including component composition, state management, performance optimization, accessibility, and responsive design. Use when building UI components, implementing frontend features, optimizing performance, or working with React/Next.js applications.
Project planning methodologies including work breakdown structure, task estimation, dependency management, risk assessment, sprint planning, and stakeholder communication. Use when breaking down projects, estimating work, planning sprints, or managing dependencies.
| name | technical-writing |
| description | Technical writing best practices including documentation structure, clear writing principles, API documentation, tutorials, changelogs, and markdown formatting. Use when writing documentation, creating READMEs, documenting APIs, or writing tutorials. |
This skill provides comprehensive guidance for creating clear, effective technical documentation that helps users and developers.
1. Tutorials (Learning-oriented)
2. How-to Guides (Problem-oriented)
3. Reference (Information-oriented)
4. Explanation (Understanding-oriented)
# Project Name
Brief description of what the project does (1-2 sentences).
[](link)
[](link)
[](link)
## Features
- Feature 1
- Feature 2
- Feature 3
## Quick Start
```bash
# Installation
npm install project-name
# Usage
npx project-name init
npm install project-name
yarn add project-name
git clone https://github.com/user/project.git
cd project
npm install
npm run build
Create a .env file:
DATABASE_URL=postgresql://user:password@localhost:5432/db
API_KEY=your_api_key
import { createClient } from 'project-name';
const client = createClient({
apiKey: process.env.API_KEY,
});
const result = await client.doSomething();
console.log(result);
[More complex example with explanations]
See API.md for complete API documentation.
See CONTRIBUTING.md for guidelines.
MIT © [Author Name]
## Clear Writing Principles
### Use Active Voice
```markdown
❌ Passive: The data is validated by the function.
✅ Active: The function validates the data.
❌ Passive: Errors should be handled by your application.
✅ Active: Your application should handle errors.
❌ Complex: Utilize the aforementioned methodology to instantiate a novel instance.
✅ Simple: Use this method to create a new instance.
❌ Jargon: Leverage our SDK to synergize with the API ecosystem.
✅ Clear: Use our SDK to connect to the API.
❌ Wordy: In order to be able to successfully complete the installation process,
you will need to make sure that you have Node.js version 18 or higher installed
on your system.
✅ Concise: Install Node.js 18 or higher.
❌ Redundant: The function returns back a response.
✅ Concise: The function returns a response.
❌ Inconsistent:
- Create a user
- Add an account
- Register a member
(All referring to the same action)
✅ Consistent:
- Create a user
- Update a user
- Delete a user
// ❌ BAD - Incomplete example
user.save();
// ✅ GOOD - Complete example
import { User } from './models';
async function createUser() {
const user = new User({
email: 'user@example.com',
name: 'John Doe',
});
await user.save();
console.log('User created:', user.id);
}
createUser();
// Calculate fibonacci number
function fibonacci(n: number): number {
if (n <= 1) return n;
return fibonacci(n - 1) + fibonacci(n - 2);
}
console.log(fibonacci(10));
// Output: 55
// Authenticate user with JWT
app.post('/api/auth/login', async (req, res) => {
const { email, password } = req.body;
const user = await User.findOne({ email });
if (!user) {
return res.status(401).json({ error: 'Invalid credentials' });
}
// 👇 Important: Always use bcrypt for password comparison
const isValid = await bcrypt.compare(password, user.passwordHash);
if (!isValid) {
return res.status(401).json({ error: 'Invalid credentials' });
}
const token = generateToken(user);
res.json({ token });
});
// ❌ BAD - No context
await client.query('SELECT * FROM users');
// ✅ GOOD - With context
// Fetch all active users who logged in within the last 30 days
const activeUsers = await client.query(`
SELECT id, email, name, last_login
FROM users
WHERE status = 'active'
AND last_login > NOW() - INTERVAL '30 days'
ORDER BY last_login DESC
`);
1. Introduction (2-3 sentences)
2. Prerequisites
3. Step-by-Step Instructions
4. Next Steps
# Building a REST API with Express
In this tutorial, you'll build a REST API for managing a todo list.
You'll learn how to create routes, handle requests, and connect to a database.
**Time**: 30 minutes
**Level**: Beginner
## Prerequisites
- Node.js 18+ installed
- Basic JavaScript knowledge
- Code editor (VS Code recommended)
## Step 1: Set Up Project
Create a new project directory and initialize npm:
```bash
mkdir todo-api
cd todo-api
npm init -y
Install Express:
npm install express
You should see express added to your package.json.
Create index.js:
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.json({ message: 'Hello, World!' });
});
const PORT = 3000;
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
});
Run the server:
node index.js
Visit http://localhost:3000 in your browser. You should see:
{ "message": "Hello, World!" }
[Continue with more steps...]
## API Documentation Patterns
### Endpoint Documentation
```markdown
## Create User
Creates a new user account.
**Endpoint**: `POST /api/v1/users`
**Authentication**: Not required
**Request Body**:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address (must be valid) |
| password | string | Yes | Password (min 8 characters) |
| name | string | Yes | User's full name (max 100 characters) |
**Example Request**:
```bash
curl -X POST https://api.example.com/v1/users \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123",
"name": "John Doe"
}'
Success Response (201 Created):
{
"id": "user_abc123",
"email": "user@example.com",
"name": "John Doe",
"createdAt": "2025-10-16T10:30:00Z"
}
Error Responses:
400 Bad Request - Invalid input:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email address",
"field": "email"
}
}
409 Conflict - Email already exists:
{
"error": {
"code": "EMAIL_EXISTS",
"message": "Email address already registered"
}
}
Rate Limit: 5 requests per minute
### Function/Method Documentation
```typescript
/**
* Calculates the total price of items including tax.
*
* @param items - Array of items to calculate total for
* @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns Total price including tax
*
* @throws {Error} If items array is empty
* @throws {Error} If taxRate is negative
*
* @example
* ```typescript
* const items = [
* { price: 10, quantity: 2 },
* { price: 15, quantity: 1 }
* ];
* const total = calculateTotal(items, 0.08);
* console.log(total); // 37.80
* ```
*/
function calculateTotal(
items: Array<{ price: number; quantity: number }>,
taxRate: number
): number {
if (items.length === 0) {
throw new Error('Items array cannot be empty');
}
if (taxRate < 0) {
throw new Error('Tax rate cannot be negative');
}
const subtotal = items.reduce(
(sum, item) => sum + item.price * item.quantity,
0
);
return subtotal * (1 + taxRate);
}
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- New feature X for Y use case
### Changed
- Improved performance of Z operation
### Fixed
- Fixed bug where A caused B
## [2.1.0] - 2025-10-16
### Added
- User profile avatars (#123)
- Email notification settings (#125)
- Two-factor authentication support (#130)
### Changed
- Updated UI for settings page (#124)
- Improved API response times by 40% (#128)
### Deprecated
- `oldFunction()` will be removed in v3.0 - use `newFunction()` instead
### Fixed
- Fixed memory leak in session management (#126)
- Corrected timezone handling in reports (#129)
### Security
- Updated dependencies to patch security vulnerabilities (#127)
## [2.0.0] - 2025-09-01
### Added
- Complete redesign of dashboard
- GraphQL API support
### Changed
- **BREAKING**: Renamed `create_user` to `createUser` for consistency
- **BREAKING**: Changed date format from `DD/MM/YYYY` to ISO 8601
### Removed
- **BREAKING**: Removed deprecated v1 API endpoints
[Unreleased]: https://github.com/user/project/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/user/project/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/user/project/releases/tag/v2.0.0
Semantic Versioning (MAJOR.MINOR.PATCH):
# H1 - Main title
## H2 - Section
### H3 - Subsection
#### H4 - Sub-subsection
**Bold text** or __bold__
*Italic text* or _italic_
***Bold and italic***
~~Strikethrough~~
`Inline code`
Unordered list:
- Item 1
- Item 2
- Nested item
- Another nested item
- Item 3
Ordered list:
1. First item
2. Second item
1. Nested item
2. Another nested item
3. Third item
Task list:
- [x] Completed task
- [ ] Incomplete task
[Link text](https://example.com)
[Link with title](https://example.com "Title text")
Inline code: `const x = 5;`
Code block:
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
```
With line highlighting:
```javascript {2}
function greet(name) {
console.log(`Hello, ${name}!`); // This line is highlighted
}
```
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | More |
| Row 2 | Data | More |
Alignment:
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
> Single line quote
> Multi-line
> quote with
> several lines
> **Note**: Important information
> **⚠️ Warning**: This action cannot be undone.
> **💡 Tip**: Use keyboard shortcuts to speed up your workflow.
> **🚨 Danger**: Never commit secrets to version control.
> **ℹ️ Info**: This feature requires Node.js 18+.
Use diagrams for:
Don't use diagrams for:
```mermaid
graph TD
A[User Request] --> B{Authenticated?}
B -->|Yes| C[Process Request]
B -->|No| D[Return 401]
C --> E[Return Response]
```
```mermaid
sequenceDiagram
Client->>API: POST /users
API->>Database: INSERT user
Database-->>API: User created
API->>Email: Send welcome email
API-->>Client: 201 Created
```
┌─────────────┐ ┌──────────────┐ ┌──────────┐
│ Client │─────▶│ API Server │─────▶│ Database │
│ (Browser) │◀─────│ (Express) │◀─────│ (Postgres)│
└─────────────┘ └──────────────┘ └──────────┘
## Installation
Install via npm:
```bash
npm install package-name
git clone https://github.com/user/package.git
cd package
npm install
npm run build
npm link
npm install package-name@2.1.0
npm install package-name react react-dom
## Quick Start (Beginner)
Get up and running in 5 minutes:
[Simple example]
## Advanced Usage
For experienced users:
[Complex example]
## Expert Topics
Deep dive into internals:
[Very advanced example]
❌ Impersonal: The configuration file should be updated.
✅ Personal: Update your configuration file.
❌ Distant: One must install the dependencies.
✅ Direct: Install the dependencies.
❌ We: Now we'll create a new user.
✅ You: Now you'll create a new user.
❌ We: We recommend using TypeScript.
✅ You: We recommend you use TypeScript.
❌ Vague: An error occurred.
✅ Helpful: Connection failed. Check your network and try again.
❌ Blaming: You entered invalid data.
✅ Helpful: The email field requires a valid email address (e.g., user@example.com).
❌ Assumes knowledge:
"Use the ORM to query the RDBMS."
✅ Explains terms:
"Use the ORM (Object-Relational Mapping tool) to query the database.
An ORM lets you interact with your database using code instead of SQL."
❌ Technical jargon:
"Leverage the API to facilitate data ingestion."
✅ Plain English:
"Use the API to import data."
## Version Compatibility
| Version | Node.js | Features |
|---------|---------|----------|
| 3.x | 18+ | Full feature set |
| 2.x | 16+ | Legacy API (deprecated) |
| 1.x | 14+ | No longer supported |
## Upgrading from 2.x to 3.x
### Breaking Changes
**1. Renamed functions**
```typescript
// v2.x
import { create_user } from 'package';
// v3.x
import { createUser } from 'package';
2. Changed date format
Dates now use ISO 8601 format:
01/15/20252025-01-15T00:00:00ZUpdate imports:
# Run this command to update your code
npx package-migrate-v3
Update date handling:
// Before
const date = '01/15/2025';
// After
const date = '2025-01-15T00:00:00Z';
Test thoroughly before deploying.
## Documentation Checklist
**Before Writing**:
- [ ] Who is the audience (beginner/intermediate/expert)?
- [ ] What do they need to accomplish?
- [ ] What do they already know?
**While Writing**:
- [ ] Use active voice
- [ ] Use simple language
- [ ] Be concise
- [ ] Provide examples
- [ ] Show expected output
**After Writing**:
- [ ] Read it aloud
- [ ] Have someone else review it
- [ ] Test all code examples
- [ ] Check all links
- [ ] Spell check
## When to Use This Skill
Use this skill when:
- Writing project READMEs
- Creating API documentation
- Writing tutorials
- Documenting code
- Creating user guides
- Writing changelogs
- Contributing to open source
- Creating internal documentation
- Writing blog posts about technical topics
- Training others on technical writing
---
**Remember**: Good documentation is empathetic. Always write for the person reading your docs at 2 AM who just wants to get their code working. Be clear, be helpful, and be kind.