如何写好技术文档

作为一个程序员，最怕的四件事情是：

1. 写代码注释;
2. 写技术文档;
3. 接手的项目没有代码注释;
4. 接手的项目没有技术文档;

这其实是一个死循环。虽然大多数人会写出一些代码注释，但是没有时间去写技术文档，或者没有时间去整理技术文档，导致项目交接的时候，接手的人根本不知道怎么使用这个项目，更别说去维护这个项目了。为此，本文将介绍如何写好技术文档，以提高项目的可维护性和可扩展性。

# 技术文档梳理

在写技术文档之前，首先需要对项目进行梳理。这包括以下几个方面：

1. 明确该技术文档写作的目的，要明确文档的受众是谁，以及要解决什么问题。
2. 明确该技术文档的创建和维护更新的日期，确保文档的时效性，避免读者踩坑。
3. 明确该技术文档的目录结构，确保文档的条理性和易读性。

# 技术文档规范

可以参考的一些文档:

1. 阮一峰老师的《中文技术文档的写作规范》open in new window
2. 《中文技术文档写作风格指南》open in new window

# 交接文档

以交接文档为例，我的写作对象是的接手的同事，所以我会从以下几个方面来写：

1. 一个较为完整的项目需求:
   1. 架构设计说明和设计思路;
   2. 关键代码目录，以及主要代码文件的功能说明、职责划分;
   3. 相关协议的功能说明;
   4. 配置的格式、位置，配置项的功能性描述;
2. 对接手人的工作建议:
   1. 代码注释的规范;
   2. 技术文档的规范;
   3. 最佳实践建议;
   4. 错误实践提示，有哪些容易出错的坑和预防清单等；
   5. 对接手人的学习建议或相关资料；
3. 接手人未来需要做的工作：
   1. 具体项目工作清单，按重要程度排序；
   2. 未完成需求的详细说明，包含进一步的开发计划中相关内容及演变方向说明；
   3. 项目相关联系人；
4. 交接文件和物品交付
   1. 账号及密码清单，若有涉密相关，则依据保密协议进行说明；
   2. 若有重要的纸质文件，除交接的纸质文件外，另需扫码并上传文档，附链接；
5. 常见问题及应对方案：
   1. 无法找到某个文件? 建议可先找 xxx 同事, 若无法解决可再寻找 xxx ...
   2. 具体项目如何操作? 建议可找 xxx 同事, 她之前负责过...
   3. ......

# 参考文献

• 《程序员交接文档》open in new window