Back to Details

reference-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Reference Documentation Patterns

参考文档模式

Reference documentation is information-oriented - helping experienced users find precise technical details quickly. This skill provides patterns for writing clear, scannable reference pages.
Dependency: Always use this skill in conjunction with 
docs-style
for core writing principles.
参考文档以信息传递为核心——帮助有经验的用户快速找到精准的技术细节。本技能提供了编写清晰、易扫描的参考页面的模式。
依赖项： 请始终结合
docs-style
技能使用，以遵循核心写作原则。

Purpose and Audience

目标与受众

  • Who: Experienced users seeking specific information
  • Goal: Quick lookup of technical details
  • Mode: Not for learning, for looking up
  • Expectation: Brevity, consistency, completeness
  • 适用人群： 有经验的、需要特定信息的用户
  • 目标： 快速查找技术细节
  • 使用场景： 用于查阅，而非学习
  • 要求： 简洁、一致、完整

Document Structure Template

文档结构模板

Use this template when creating reference documentation:
markdown
---
title: "[Symbol/API Name]"
description: "One-line description of what it does"
---
创建参考文档时可使用以下模板：
markdown
---
title: "[Symbol/API Name]"
description: "One-line description of what it does"
---

[Name]

[Name]

Brief description (1-2 sentences). State what it is and its primary purpose.
Brief description (1-2 sentences). State what it is and its primary purpose.

Parameters

Parameters

NameTypeRequiredDescription
param1
string
YesWhat this parameter controls
param2
number
NoOptional behavior modification. Default: 
10
NameTypeRequiredDescription
param1
string
YesWhat this parameter controls
param2
number
NoOptional behavior modification. Default: 
10

Returns

Returns

TypeDescription
ReturnType
What the function returns and when
TypeDescription
ReturnType
What the function returns and when

Example

Example

language
import { symbolName } from 'package';

// Complete, runnable example showing common use case
const result = symbolName({
  param1: 'realistic-value',
  param2: 42
});

console.log(result);
// Expected output: { ... }
language
import { symbolName } from 'package';

// Complete, runnable example showing common use case
const result = symbolName({
  param1: 'realistic-value',
  param2: 42
});

console.log(result);
// Expected output: { ... }

Related

Related

undefined
undefined

Writing Principles

写作原则

Brevity Over Explanation

简洁优先，避免冗余解释

  • State facts, not rationale
  • Avoid "why" - save that for Explanation docs
  • Cut unnecessary words
Do:
markdown
Returns the user's display name.
Avoid:
markdown
This function is useful when you need to get the user's display name
because it handles all the edge cases for you automatically.
  • 陈述事实，而非理由
  • 避免解释“为什么”——这类内容放在说明文档中
  • 删除冗余表述
正确示例：
markdown
Returns the user's display name.
错误示例：
markdown
This function is useful when you need to get the user's display name
because it handles all the edge cases for you automatically.

Scannable Tables, Not Prose

使用易扫描的表格，而非大段文字

Do:
markdown
| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | Unique user identifier |
| `options` | `Options` | Configuration object |
Avoid:
markdown
The first parameter is `userId`, which should be a string containing
the unique user identifier. The second parameter is `options`, which
is an Options object containing the configuration.
正确示例：
markdown
| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | Unique user identifier |
| `options` | `Options` | Configuration object |
错误示例：
markdown
The first parameter is `userId`, which should be a string containing
the unique user identifier. The second parameter is `options`, which
is an Options object containing the configuration.

Consistent Format Across Entries

保持条目格式一致

All reference pages for similar items should follow identical structure:
  • Same heading order
  • Same table columns
  • Same code example format
  • Same related links section
同类参考页面需遵循完全一致的结构：
  • 相同的标题顺序
  • 相同的表格列
  • 相同的代码示例格式
  • 相同的相关链接板块

Every Example Must Be Runnable

所有示例必须可运行

  • Include all imports
  • Show complete, working code
  • Use realistic values (not "foo", "bar", "test123")
  • Include expected output when helpful
  • 包含所有必要的导入语句
  • 展示完整、可运行的代码
  • 使用真实合理的取值（而非"foo"、"bar"、"test123"）
  • 必要时标注预期输出

Code Example Patterns

代码示例模式

Show Common Use Case First

优先展示常用场景

markdown
undefined
markdown
undefined

Example

Example

Basic Usage

Basic Usage

typescript
const user = await getUser('user-123');
console.log(user.name);
typescript
const user = await getUser('user-123');
console.log(user.name);

With Options

With Options

typescript
const user = await getUser('user-123', {
  includeMetadata: true,
  fields: ['name', 'email', 'role']
});
undefined
typescript
const user = await getUser('user-123', {
  includeMetadata: true,
  fields: ['name', 'email', 'role']
});
undefined

Include Setup and Context

包含初始化与上下文

markdown
```typescript
import { Client } from '@example/sdk';

// Initialize client (required once per application)
const client = new Client({ apiKey: process.env.API_KEY });

// Now use the function
const result = await client.users.list();
undefined
markdown
```typescript
import { Client } from '@example/sdk';

// Initialize client (required once per application)
const client = new Client({ apiKey: process.env.API_KEY });

// Now use the function
const result = await client.users.list();
undefined

Use Realistic Values

使用真实合理的取值

Do: 
userId: 'usr_a1b2c3d4'
Avoid: 
userId: 'foo'
Do: 
email: 'jane.smith@company.com'
Avoid: 
email: 'test@test.com'
正确示例： 
userId: 'usr_a1b2c3d4'
错误示例： 
userId: 'foo'
正确示例： 
email: 'jane.smith@company.com'
错误示例： 
email: 'test@test.com'

Parameter Documentation Patterns

参数文档模式

Required vs Optional

必填与可选参数

Clearly indicate which parameters are required:
markdown
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your API key |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `retries` | `number` | No | `3` | Number of retry attempts |
清晰标注哪些参数是必填项：
markdown
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your API key |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `retries` | `number` | No | `3` | Number of retry attempts |

Complex Types

复杂类型

For object parameters, document the shape:
markdown
undefined
对于对象类型的参数，需说明其结构：
markdown
undefined

Parameters

Parameters

NameTypeRequiredDescription
options
UserOptions
NoConfiguration options
NameTypeRequiredDescription
options
UserOptions
NoConfiguration options

UserOptions

UserOptions

PropertyTypeRequiredDescription
includeDeleted
boolean
NoInclude soft-deleted users
fields
string[]
NoFields to return
limit
number
NoMaximum results (default: 100)
undefined
PropertyTypeRequiredDescription
includeDeleted
boolean
NoInclude soft-deleted users
fields
string[]
NoFields to return
limit
number
NoMaximum results (default: 100)
undefined

Enum Values

枚举值

Document allowed values clearly:
markdown
| Name | Type | Values | Description |
|------|------|--------|-------------|
| `status` | `string` | `active`, `pending`, `suspended` | User account status |
清晰说明允许的取值：
markdown
| Name | Type | Values | Description |
|------|------|--------|-------------|
| `status` | `string` | `active`, `pending`, `suspended` | User account status |

Return Value Documentation

返回值文档

Simple Returns

简单返回值

markdown
undefined
markdown
undefined

Returns

Returns

User
- The requested user object, or 
null
if not found.
undefined
User
- The requested user object, or 
null
if not found.
undefined

Complex Returns

复杂返回值

markdown
undefined
markdown
undefined

Returns

Returns

PropertyTypeDescription
data
User[]
Array of user objects
pagination
Pagination
Pagination metadata
total
number
Total matching records
undefined
PropertyTypeDescription
data
User[]
Array of user objects
pagination
Pagination
Pagination metadata
total
number
Total matching records
undefined

Error Conditions

错误场景

markdown
undefined
markdown
undefined

Errors

Errors

ErrorCondition
NotFoundError
User does not exist
UnauthorizedError
Invalid or expired API key
RateLimitError
Too many requests
undefined
ErrorCondition
NotFoundError
User does not exist
UnauthorizedError
Invalid or expired API key
RateLimitError
Too many requests
undefined

API Reference Specifics

API参考文档细节

HTTP Endpoints

HTTP接口

markdown
undefined
markdown
undefined

Endpoint

Endpoint

http
GET /api/v1/users/{userId}
http
GET /api/v1/users/{userId}

Path Parameters

Path Parameters

NameTypeDescription
userId
string
The user's unique identifier
NameTypeDescription
userId
string
The user's unique identifier

Query Parameters

Query Parameters

NameTypeRequiredDescription
fields
string
NoComma-separated list of fields
NameTypeRequiredDescription
fields
string
NoComma-separated list of fields

Headers

Headers

NameRequiredDescription
Authorization
YesBearer token
X-Request-ID
NoRequest tracking ID
NameRequiredDescription
Authorization
YesBearer token
X-Request-ID
NoRequest tracking ID

Response

Response

json
{
  "id": "usr_a1b2c3d4",
  "name": "Jane Smith",
  "email": "jane@company.com"
}
undefined
json
{
  "id": "usr_a1b2c3d4",
  "name": "Jane Smith",
  "email": "jane@company.com"
}
undefined

Component/Props Reference

组件/属性参考文档

For UI components:
markdown
undefined
针对UI组件：
markdown
undefined

Props

Props

PropTypeDefaultDescription
variant
'primary' | 'secondary'
'primary'
Visual style
size
'sm' | 'md' | 'lg'
'md'
Button size
disabled
boolean
false
Disable interactions
onClick
() => void
-Click handler
PropTypeDefaultDescription
variant
'primary' | 'secondary'
'primary'
Visual style
size
'sm' | 'md' | 'lg'
'md'
Button size
disabled
boolean
false
Disable interactions
onClick
() => void
-Click handler

Slots

Slots

NameDescription
default
Button content
icon
Icon to display before text
undefined
NameDescription
default
Button content
icon
Icon to display before text
undefined

Related Links Section

相关链接板块

Always include links to related content:
markdown
undefined
请始终包含相关内容的链接：
markdown
undefined

Related

Related

undefined
undefined

Checklist for Reference Pages

参考页面检查清单

Before considering a reference page complete:
  • Title matches the symbol/API name exactly
  • Description is one clear sentence
  • All parameters documented with types
  • Required vs optional clearly marked
  • Default values specified for optional parameters
  • Return type and structure documented
  • At least one complete, runnable example
  • Example uses realistic values
  • Related pages linked
  • Format matches other reference pages in the docs
参考页面完成前，请确认以下事项：
  • 标题与符号/API名称完全一致
  • 描述为清晰的单句
  • 所有参数均已标注类型
  • 必填与可选参数已清晰区分
  • 可选参数已说明默认值
  • 返回值类型与结构已文档化
  • 至少包含一个完整、可运行的示例
  • 示例使用了真实合理的取值
  • 已链接相关页面
  • 格式与文档集中其他参考页面一致