type
status
date
slug
summary
tags
category
icon
password
技术文档编写有助于我们更好梳理业务的来龙去脉，以及分析技术细节，在编写的过程可以查漏补缺，可以在沟通过程中，反复校对以达到方案更加完善的目的。
一、基本原则
确定目标读者
知晓目标读者是谁非常重要。这将决定写作风格，使用的术语，以及需要解释多少背景信息。
使用清晰的标题和副标题
清晰具体的标题和副标题不仅能使读者更快的找到他们需要的信息，同样也提供了文档的一个基本架构。
提供简洁的摘要
一份好的技术文档应该以摘要开始，简明的总结出文档的内容，这样读者可以判断这篇文档是否包含了他们需要的信息。
使用列表和图表
长段落的文字可能会使读者感到厌倦，通过列表和图表来归纳和解释内容可以提高文档的可读性。
定义专业术语
如果你的文档中包含了专业术语，确保你已经给出了一个清晰的定义或者解释。
使用具体例子
例子可以帮助读者理解抽象的概念或者理论。在可能的情况下，尽量提供实例以使理论变得更加具体和生动。
重复检查你的文档
在发布之前，确保你至少检查了两遍你的文档。检查可能的打字错误，语法错误，以及信息的准确性。
获取反馈并修改
当你完成文档后，获取一些读者或者其他人的反馈。他们可能会发现你未曾注意到的问题或误解，这将有助于你改进文档的质量。
保持文档更新
技术不断地发展和变化，所以你的文档也需要随之更新。即便没有新的技术变化，你也应定期检查并更新你的文档。
二、目录框架
可以通过以下目录结构，来编写文档内容
- 背景及目标
1. 简要描述需求的上下文背景、核心逻辑
2. 着重从技术视角阐述本质需求（已知问题、历史原因、技术限制）
3. 可选：了解需求的「产品价值」、核心逻辑，即做了会有什么收益
4. 可选：数据指标：确定可以量化的业务/技术指标
- 相关信息（Table形式展示）
- 需求文档
- 需求单地址
- UI/UE设计稿
- 相关人员介绍
- 关联技术方案（后端、架构）
- 接口文档
- 代码仓库
- MR合并地址
- 测试Case地址
- 部署环境（泳道、访问地址）
- 专业术语（名词解释）
- 技术方案调研
1. 结合业务场景，提供多个可选方案，并说明其「详细设计」、「实现成本」、「优缺点」。
2. 为后续方案设计提供理论依据。
- 任务拆解排期
- 修订历史
- 联系信息
- 参考资料
- FAQ
技术方案
由于技术方案必要时，可以添加对应的流程图、思维导图等作为补充，这样在对外沟通时，会更加清晰和高效。
- 作者:HRope
- 链接:https://hrope.cn/article/technical-document-writing
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。