Back to Details

documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Documentation

技术文档

Write clear, maintainable technical documentation for different audiences and purposes.
为不同受众和用途编写清晰、可维护的技术文档。

Document Types

文档类型

README

README

  • What this is and why it exists
  • Quick start (< 5 minutes to first success)
  • Configuration and usage
  • Contributing guide
  • 文档的定义与存在意义
  • 快速入门（首次成功操作耗时<5分钟）
  • 配置与使用方法
  • 贡献指南

API Documentation

API文档

  • Endpoint reference with request/response examples
  • Authentication and error codes
  • Rate limits and pagination
  • SDK examples
  • 包含请求/响应示例的端点参考
  • 认证方式与错误代码
  • 速率限制与分页机制
  • SDK示例

Runbook

Runbook

  • When to use this runbook
  • Prerequisites and access needed
  • Step-by-step procedure
  • Rollback steps
  • Escalation path
  • 本手册的适用场景
  • 前置条件与所需权限
  • 分步操作流程
  • 回滚步骤
  • 升级路径

Architecture Doc

架构文档

  • Context and goals
  • High-level design with diagrams
  • Key decisions and trade-offs
  • Data flow and integration points
  • 背景与目标
  • 含示意图的高层级设计
  • 关键决策与权衡考量
  • 数据流与集成点

Onboarding Guide

Onboarding Guide

  • Environment setup
  • Key systems and how they connect
  • Common tasks with walkthroughs
  • Who to ask for what
  • 环境搭建
  • 核心系统及其关联关系
  • 常见任务实操演练
  • 问题对接联系人

Principles

编写原则

  1. Write for the reader — Who is reading this and what do they need?
  2. Start with the most useful information — Don't bury the lede
  3. Show, don't tell — Code examples, commands, screenshots
  4. Keep it current — Outdated docs are worse than no docs
  5. Link, don't duplicate — Reference other docs instead of copying
  1. 为读者而写 — 明确读者是谁，他们需要什么信息？
  2. 从最有价值的信息入手 — 不要把关键内容藏在后面
  3. 展示而非说教 — 提供代码示例、命令、截图
  4. 保持内容更新 — 过时的文档不如没有文档
  5. 链接而非重复 — 引用其他文档而非复制内容