Back to Details

documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation

技术文档编写

Create clear, maintainable technical documentation that serves your audience.
创建清晰、可维护的技术文档，为目标受众服务。

Key Principles

核心原则

  • Documentation as code — docs live with code, version with code, review with code
  • Audience-first writing — write for who's reading, not what you know
  • Maintainability over completeness — inaccurate docs are worse than no docs
  • Link to source of truth — don't duplicate information across docs
  • 文档即代码 —— 文档与代码共存、随代码版本化、随代码一同评审
  • 受众优先的写作 —— 为读者而写，而非为自己的知识储备而写
  • 可维护性优先于完整性 —— 不准确的文档比没有文档更糟
  • 链接至权威来源 —— 不要在不同文档中重复信息

Quick Start Checklist

快速启动清单

  1. Identify documentation type (README, API docs, ADR, user guide)
  2. Determine audience (all users, developers, team, contributors)
  3. Follow type-specific template from references
  4. Include working examples (test them!)
  5. Link to related documentation
  1. 确定文档类型（README、API文档、ADR、用户指南）
  2. 明确目标受众（所有用户、开发者、团队成员、贡献者）
  3. 遵循参考资料中对应类型的模板
  4. 包含可运行的示例（记得测试！）
  5. 链接至相关文档

Documentation Types

文档类型

TypeWhen to UseAudience
READMEProject entry pointAll users
API DocsEndpoint referenceDevelopers
ADRMajor decisionsTeam/future devs
User GuideTask completionEnd users
类型使用场景目标受众
README项目入口文档所有用户
API文档端点参考开发者
ADR重大决策留存团队成员/未来开发者
用户指南任务完成指引终端用户

References

参考资料

ReferenceDescription
readme-guide.mdREADME templates, section patterns, badges
api-docs.mdAPI documentation patterns, OpenAPI integration
adr-guide.mdArchitecture Decision Record format and workflow
diagrams.mdMermaid diagram patterns for common scenarios
readme-template.mdTemplate for project README files
adr-template.mdTemplate for Architecture Decision Records
参考资料说明
readme-guide.mdREADME模板、章节范式、标识徽章
api-docs.mdAPI文档范式、OpenAPI集成
adr-guide.md架构决策记录格式与工作流
diagrams.md常见场景下的Mermaid图表范式
readme-template.md项目README文件模板
adr-template.md架构决策记录模板