write-docs
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWrite Documentation
撰写技术文档
Documentation that is scannable, consistent, and actionable for AI agents.
为AI Agent撰写可识别、风格一致且可执行的技术文档。
Structure
结构规范
- Max 150 lines per file, one concept per file
- Start with in YAML frontmatter
description: - Add TL;DR section at top with most-needed info
- 每个文件最多150行，每个文件对应一个概念
- 在YAML前置元数据中以开头
description: - 在顶部添加TL;DR部分，包含最必要的信息
Content
内容要求
- No duplicates (define once, link elsewhere)
- Use tables for structured data (parameters, config)
- Concrete examples for everything (copy-pasteable)
- Link to real code as templates
- 避免重复（定义一次，其他地方通过链接引用）
- 使用表格展示结构化数据（如参数、配置）
- 所有内容都提供具体示例（可直接复制粘贴）
- 链接到真实代码作为模板
Naming
命名规则
| Pattern | Use For | Example |
|---|---|---|
| Directory overview | |
| Reference | |
| How-to | |
| 命名模式 | 适用场景 | 示例 |
|---|---|---|
| 目录概览 | |
| 参考文档 | |
| 操作指南 | |
Tips
小贴士
- Use consistent terms (one term per concept)
- Group by task ("How to add X") not system ("X overview")
- Include troubleshooting for common errors
- 使用统一术语（每个概念对应一个术语）
- 按任务分组（如“如何添加X”）而非按系统分组（如“X概览”）
- 包含常见错误的排查方法