Back to Details

documentation-engineer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Engineer

文档工程师

Expert in creating clear, comprehensive, and maintainable technical documentation.
擅长创建清晰、全面、可维护的技术文档。

When This Skill Activates

技能触发场景

Activates when you:
  • Ask to write documentation
  • Request README creation
  • Mention "docs" or "document this"
  • Need API documentation
当你有以下需求时触发：
  • 要求撰写文档
  • 请求创建README
  • 提及「docs」或者「document this」
  • 需要API文档

Documentation Types

文档类型

1. README

1. README

Every project should have a README with:
markdown
undefined
每个项目都应该包含一个具备以下内容的README：
markdown
undefined

Project Name

Project Name

Brief description (what it does, why it exists)
Brief description (what it does, why it exists)

Quick Start

Quick Start

Installation and usage in 3 steps or less.
Installation and usage in 3 steps or less.

Installation

Installation

Detailed installation instructions.
Detailed installation instructions.

Usage

Usage

Examples of common usage patterns.
Examples of common usage patterns.

Configuration

Configuration

Environment variables and configuration options.
Environment variables and configuration options.

Development

Development

How to run tests, build, and develop locally.
How to run tests, build, and develop locally.

Contributing

Contributing

Guidelines for contributors.
Guidelines for contributors.

License

License

License information.
undefined
License information.
undefined

2. API Documentation

2. API文档

For each endpoint/function:
  • Description: What it does
  • Parameters: Name, type, required/optional, description
  • Return value: Type and structure
  • Errors: Possible errors and conditions
  • Examples: Usage examples
针对每个端点/函数：
  • 描述：功能说明
  • 参数：名称、类型、必填/选填、描述
  • 返回值：类型和结构
  • 错误：可能出现的错误及触发条件
  • 示例：使用示例

3. Code Comments

3. 代码注释

Comment why, not what:
typescript
// Bad: Sets the count to zero
count = 0;

// Good: Reset count for new measurement cycle
count = 0;

// Bad: Check if user is admin
if (user.role === 'admin') {

// Good: Only admins can bypass approval workflow
if (user.role === 'admin') {
注释要写为什么这么做，而不是做了什么：
typescript
// Bad: Sets the count to zero
count = 0;

// Good: Reset count for new measurement cycle
count = 0;

// Bad: Check if user is admin
if (user.role === 'admin') {

// Good: Only admins can bypass approval workflow
if (user.role === 'admin') {

4. Architecture Documentation

4. 架构文档

  • System overview
  • Component relationships
  • Data flow
  • Design decisions
  • Trade-offs considered
  • 系统概览
  • 组件关系
  • 数据流
  • 设计决策
  • 权衡考虑

Documentation Principles

文档编写原则

  1. Be Clear: Use simple, direct language
  2. Be Concise: Respect the reader's time
  3. Be Accurate: Keep docs in sync with code
  4. Be Complete: Cover all public interfaces
  5. Be Current: Update docs when code changes
  1. 清晰易懂：使用简单直接的语言
  2. 简洁凝练：尊重读者的时间
  3. 准确无误：保持文档与代码同步
  4. 内容完整：覆盖所有对外公开的接口
  5. 及时更新：代码变更时同步更新文档

Writing Guidelines

编写规范

Headings

标题

  • Use sentence case for headings
  • Start with a verb or noun
  • Be descriptive
  • 标题使用句首字母大写格式
  • 以动词或名词开头
  • 具备描述性

Code Examples

代码示例

  • Show before/after when appropriate
  • Include import statements
  • Show expected output
  • Handle edge cases
  • 合适的情况下展示修改前后的对比
  • 包含import语句
  • 展示预期输出
  • 覆盖边界情况

Links

链接

  • Use relative links for internal docs
  • Include anchors for sections
  • Test that links work
  • 内部文档使用相对链接
  • 为章节添加锚点
  • 测试链接可正常访问

Diagrams

图表

  • Use Mermaid for flowcharts and sequences
  • Keep diagrams simple
  • Add a title and legend
  • 流程图和时序图使用Mermaid
  • 保持图表简洁
  • 添加标题和图例

Documentation Checklist

文档检查清单

README

README

  • Project description
  • Quick start guide
  • Installation instructions
  • Usage examples
  • Configuration guide
  • Contributing guidelines
  • 项目描述
  • 快速入门指南
  • 安装说明
  • 使用示例
  • 配置指南
  • 贡献指南

Code Docs

代码文档

  • All public functions documented
  • Parameters and returns documented
  • Examples provided for complex functions
  • Edge cases documented
  • 所有公开函数均已记录
  • 参数和返回值均已说明
  • 复杂函数提供了使用示例
  • 边界情况均已记录

API Docs

API文档

  • All endpoints documented
  • Request/response schemas
  • Authentication requirements
  • Error responses documented
  • Rate limits documented
  • 所有端点均已记录
  • 请求/响应schemas
  • 鉴权要求
  • 错误响应均已记录
  • 限流规则均已记录

Scripts

脚本

Generate documentation structure:
bash
python scripts/generate_docs.py
Validate documentation:
bash
python scripts/validate_docs.py
生成文档结构：
bash
python scripts/generate_docs.py
校验文档：
bash
python scripts/validate_docs.py

References

参考资料

  • references/readme-template.md
    - README template
  • references/api-template.md
    - API documentation template
  • references/style-guide.md
    - Documentation style guide
  • references/readme-template.md
    - README模板
  • references/api-template.md
    - API文档模板
  • references/style-guide.md
    - 文档风格指南