【旧文】技术文档编写建议

本文成文于 2022.07，本来是我为团队新同事编撰的新人大礼包的一部分，后于 2024.07 发布在腾讯云开发者公众号，这里做备份记录。在 AI 能越来越强的今天，学习技术文档写作另有两方面的好处：

• 知道什么是好的文档。当前 AI 味的文章充斥各处，信息含量极低，急需整治。
  
• 梳理自己的头脑。文档的核心是头脑、思路，文字只是呈现工具。
  

 

 
原文正文：
写技术文档是开发者的义务，它和写可读代码一样重要，它也可以体现个人做事态度、逻辑思考能力。
1. 用什么载体

• 持久沉淀的文档：建议使用可以被多人看到、可以被检索的知识库工具，譬如：公司内的 wiki 或者归属于组织的知识库。不建议使用私人文档，或者 word 等无法规模化传播的工具。
  
• 短时间多人协作的文档：首选腾讯文档之类的在线多人协作工具。
  
• 整体建议：评审、共建类的文档，可以采用腾讯文档，最终定稿之后使用腾讯文档知识库或者其他长久存储工具。
  

2. 需要写哪些文档

文档是高效沟通、高效协作、知识沉淀、知识分享的工具。鼓励写文档，但也不推荐事无巨细的流水账式写文档。这些情况下需要写文档。

• 模块的整体架构设计文档，譬如：《检索引擎架构设计详解》、《检索内核整体设计》、《在线检索体系设计》 、《内容架构重构方案》 等等；
  
• 模块的关键功能设计文档，譬如：《检索引擎打分排序设计》、《检索引擎性能评测框架》 等等；
  
• 通用经验沉淀，譬如：《时间戳转换时间字符串导致服务卡死》、《流水线构建说明手册》、《GCC8 编译优化 BUG 导致的内存走漏》 等等；
  
• 项目经验总结，譬如：《检索引擎体系升级项目总结》、《检索引擎内核建库阶段性能优化》、《内容架构重构项目总结》 等等；
  
• 给其他开发者提供开发框架文档，譬如：《检索内核 C++ 打分插件开发及使用文档》、《内容接入体系算子开发手册》 等等；
  
• 提供给使用者的功能先容文档，譬如：《快速入门——检索引擎接入说明》、《force 召回干预使用说明》 等等；
  
• 复杂 case 排查的总结文档，譬如：《文档入库时效性滞后排查》、《未召回相干文档排查》 等等；
  
• 调研总结文档，譬如：《ES 检索获取匹配词方式调研》、《Lua 插件性能调研》 等等；
  
• 新人入门类文档，譬如：《检索引擎新人大礼包》、《从入职第1天到第1个需求》、《搜刮中台开发入门手册》 等等；
  

总的来说，对多个读者有价值的文档，才值得一写。
3.  怎么写好文档

3.1 文档模板

文档的内容、结构决定了文档的质量，如无特殊说明，技术文档应该采用固定的模板编写。当前我们团队已有的技术文档模板包括：

• 【模板】背景串讲文档模板
  
• 【模板】背景性能评测文档模板
  
• 【模板】背景架构评审文档模板
  
• 【模板】技术产品Case调查总结文档模板
  
• 【模板】Case Study模板
  

3.2. 排版格式

3.2.1 目录规范

• 内容超过一屏的文档，必须有目录
  
• 目录必须有数字序号
  

3.2.2. 撰写者和编辑者规范

文档必须有 owner，也必须答应开放协作，要求在文章开头插入文章的主要作者（撰写）和参与编辑作者（编辑）。
例子：

 3.2.3. 中英文/数字/标点规范

规范细则：chinese-copywriting-guidelines/README.zh-Hans.md at master · sparanoid/chinese-copywriting-guidelines · GitHub
核心要点：

• 中文与英文/数字之间需要增长空格
  
• 数字与单位之间需要增长空格
  
• 全角标点与其他字符之间不加空格
  
• 使用全角中文标点
  

3.3. 内容组织

3.3.1. 核心原则

• 目标：让读者⾼效地获得预期信息
  
• 特点：正确、完整、清晰、聚焦
  
• 关键词：简便清晰、内容单一、完整正确、有层次、面向读者
  

3.3.2. 呈现工具

假如有些步骤比较复杂，建议使用 gif 图，比贴图片更详细，又不会像视频那么重。推荐 ScreenToGif 工具，支持录屏 gif，还可以编辑每一帧，加上文字说明。
3.3.3. 合适的粒度

文档应该避免粒度过粗，导致内容衔接不上（不完整）；也避免粒度过细，影响阅读服从（不简便）。粒度的粗细程度，根据文档将要面临的读者类型而定。
3.4. 技术评审文档建议

技术评审文档是我们日常写得较多的文档，下面举两个例子
3.4.1. 从 0 开始搭建的架构

按照金字塔原理，层层递进，思路如下：
1. 目标和背景，形貌清楚为什么你要做、要做成什么样
2. 整体架构，给出架构的整体视图，包括：功能架构图、模块架构图
3. 方案细节，以功能架构图、模块架构图为蓝本，先容详细设计
4. 方案权衡，行业是怎么做的，为什么选择这个方案
5. 工作排期，给出开发人日，什么时候开始，什么时候完成
6. 其它，根据业务特点，需要给出来的一些附加信息，譬如：调研陈诉、参考信息等等，当内容比较多时，独立放到另外一个文档中
3.4.2. 对已有功能点的优化

按照金字塔原理，问题--> 问题拆解 --> 办理方案分类归并，思路如下：
1. 背景/提出问题：形貌清楚为什么要做优化
2. 发散方案：可以发散的提出各种办理方案，也可以是对上面问题的进一步分析，行业方案对比也放在这里形貌，除非内容非常多需要单独放一个文档
3. 收敛方案：已经将方案明确下来，这里只探讨明确下来的方案细节，可以是有唯一方案，也可以是有多个方案备选
4. 工作排期：
　　偶然候在【1. 背景/提出问题】这里提出问题的同时就已经包含了办理方案
　　必须围绕着问题展开讨论，紧贴问题，不要把跟主题不相干的内容放到分析里，也不要给出一个泛泛而谈的问题，问题太泛会导致分析没有针对性，假如一个问题点太大，需要拆小了分析
4.  文档的维护

文档是跨越时间限定的交流，而时间也可能让文档过时，因此文档需要持续维护。
4.1. owner 制度

单篇文档，由文档 owner 负责维护，其他同学假如有发现错误，也可以随时更新，文档 owner 负责整体审核。系列文档，由方向负责人整体承担文档的质量。
4.2. 例行更新和按需更新

文档维护和代码质量维护一样重要且耗费人力。基于投入产出比的思量，通常建议将更新分为两种类型。一种是必须及时更新的，譬如：技术产品对外的接口文档，需要结合迭代进度在每次技术升级时例行更新。另一种是读者不多，更新滞后影响较小的，譬如：给团队新人阅读的新人手册，可以在有新人入职时再更新。
5. 推荐阅读书籍

• 《金字塔原理》
  
• 《一本小小的红色写作书》
  

 
本文所在：https://www.cnblogs.com/cswuyg/p/23155401

免责声明：如果侵犯了您的权益，请联系站长及时删除侵权内容，谢谢合作！qidao123.com:ToB企服之家，中国第一个企服评测及软件市场,开放入驻,技术点评得现金.