成长路上不孤单😊😊😊😊😊😊
【14后😊///C++爱好者😊///持续分享所学😊///如有需要欢迎收藏转发///😊】
今日分享关于技术文档写作的相关内容!
关于【技术文档写作】
目录:
- 一、前言
- 二、用什么载体
- 三、需要写哪些文档
- 四、写好文档过程
- 五、文档的维护
- 六、关键步骤和技巧
一、前言
在技术的浩瀚海洋中,一份优秀的技术文档宛如精准的航海图。它是知识传承的载体,是团队协作的桥梁,更是产品成功的幕后英雄。然而,打造这样一份出色的技术文档并非易事。
其实,做为程序员最讨厌的有两类人,一类是不写文档的人,一类是让自己写文档的人。但是一篇上下文详尽、边界清晰的文档,能够前置性地解决很多问题,避免因为信息差而带来的各种来回追问、扯皮。 写技术文档是开发者的义务,它和写可读代码一样重要,它也可以体现个人做事态度、逻辑思考能力。本篇博文着重分享如何做好一份高质量的技术文档,希望能够为您起到参考作用!
二、用什么载体
- 持久沉淀的文档:建议使用可以被多人看到、可以被检索的知识库工具,譬如:公司内的 wiki 或者归属于组织的知识库。不建议使用私人文档,或者 word 等无法规模化传播的工具。
- 短时间多人协作的文档:首选腾讯文档之类的在线多人协作工具。
- 整体建议:评审、共建类的文档,可以采用腾讯文档,最终定稿之后使用腾讯文档知识库或者其他长久存储工具。
三、需要写哪些文档
文档是高效沟通、高效协作、知识沉淀、知识分享的工具。鼓励写文档,但也不推荐事无巨细的流水账式写文档。这些情况下需要写文档。
- 模块的整体架构设计文档,譬如:《检索引擎架构设计详解》、《检索内核整体设计》、《在线检索系统设计》 、《内容架构重构方案》 等等;
- 模块的关键功能设计文档,譬如:《检索引擎打分排序设计》、《检索引擎性能评测框架》 等等;
- 通用经验沉淀,譬如:《时间戳转换时间字符串导致服务卡死》、《流水线构建说明手册》、《GCC8 编译优化 BUG 导致的内存泄漏》 等等;
- 项目经验总结,譬如:《检索引擎系统升级项目总结》、《检索引擎内核建库阶段性能优化》、《内容架构重构项目总结》 等等;
- 给其他开发者提供开发框架文档,譬如:《检索内核 C++ 打分插件开发及使用文档》、《内容接入系统算子开发手册》 等等;
- 提供给使用者的功能介绍文档,譬如:《快速入门——检索引擎接入说明》、《force 召回干预使用说明》 等等;
- 复杂 case 排查的总结文档,譬如:《文档入库时效性滞后排查》、《未召回相关文档排查》 等等;
- 调研总结文档,譬如:《ES 检索获取匹配词方式调研》、《Lua 插件性能调研》 等等;
- 新人入门类文档,譬如:《检索引擎新人大礼包》、《从入职第1天到第1个需求》、《搜索中台开发入门手册》 等等;
总的来说,对多个读者有价值的文档,才值得一写。
四、写好文档过程
1、文档模板
文档的内容、结构决定了文档的质量,如无特殊说明,技术文档应该采用固定的模板编写。当前我们团队已有的技术文档模板包括:
- 【模板】后台串讲文档模板
- 【模板】后台性能评测文档模板
- 【模板】后台架构评审文档模板
- 【模板】技术产品 Case 调查总结文档模板
- 【模板】Case Study 模板
2、排版格式
目录规范
- 内容超过一屏的文档,必须有目录。
- 目录必须有数字序号。
撰写者和编辑者规范
文档必须有 owner,也必须允许开放协作,要求在文章开头插入文章的主要作者(撰写)和参与编辑作者(编辑)。例如:
中英文/数字/标点规范
核心要点:
- 中文与英文/数字之间需要增加空格。
- 数字与单位之间需要增加空格。
- 全角标点与其他字符之间不加空格。
- 使用全角中文标点。
3、内容组织
核心原则
- 目标:让读者⾼效地获得预期信息。
- 特点:准确、完整、清晰、聚焦。
- 关键词:简洁清晰、内容单一、完整准确、有层次、面向读者。
呈现工具
如果有些步骤比较复杂,建议使用 gif 图,比贴图片更详细,又不会像视频那么重。推荐 ScreenToGif 工具,支持录屏 gif,还可以编辑每一帧,加上文字说明。
合适的粒度
文档应该避免粒度过粗,导致内容衔接不上(不完整);也避免粒度过细,影响阅读效率(不简洁)。粒度的粗细程度,根据文档将要面对的读者类型而定。
4、 技术评审文档建议
技术评审文档是我们日常写得较多的文档,下面举两个例子。
从 0 开始搭建的架构
按照金字塔原理,层层递进,思路如下:
- 目标和背景,描述清楚为什么你要做、要做成什么样。
- 整体架构,给出架构的整体视图,包括:功能架构图、模块架构图。
- 方案细节,以功能架构图、模块架构图为蓝本,介绍详细设计。
- 方案权衡,行业是怎么做的,为什么选择这个方案。
- 工作排期,给出开发人日,什么时候开始,什么时候完成。
- 其它,根据业务特点,需要给出来的一些附加信息,譬如:调研报告、参考信息等等,当内容比较多时,独立放到另外一个文档中。
对已有功能点的优化
按照金字塔原理,问题--> 问题拆解 --> 解决方案分类归并,思路如下:
- 背景/提出问题:描述清楚为什么要做优化。
- 发散方案:可以发散的提出各种解决方案,也可以是对上面问题的进一步分析,行业方案对比也放在这里描述,除非内容非常多需要单独放一个文档。
- 收敛方案:已经将方案明确下来,这里只探讨明确下来的方案细节,可以是有唯一方案,也可以是有多个方案备选。
- 工作排期:
- 有时候在【1. 背景/提出问题】这里提出问题的同时就已经包含了解决方案。
- 必须围绕着问题展开讨论,紧贴问题,不要把跟主题不相干的内容放到分析里,也不要给出一个泛泛而谈的问题,问题太泛会导致分析没有针对性,如果一个问题点太大,需要拆小了分析。
五、文档的维护
文档是跨越时间限制的交流,而时间也可能让文档过时,因此文档需要持续维护。
owner 制度
单篇文档,由文档 owner 负责维护,其他同学如果有发现错误,也可以随时更新,文档 owner 负责整体审核。系列文档,由方向负责人整体承担文档的质量。
例行更新和按需更新
文档维护和代码质量维护一样重要且耗费人力。基于投入产出比的考虑,通常建议将更新分为两种类型。一种是必须及时更新的,譬如:技术产品对外的接口文档,需要结合迭代进度在每次技术升级时例行更新。另一种是读者不多,更新滞后影响较小的,譬如:给团队新人阅读的新人手册,可以在有新人入职时再更新。
六、关键步骤和技巧
-
明确文档目的与受众:在撰写技术文档前,需精准定位文档的用途与面向的读者群体。若为开发团队内部参考,可使用专业术语,深入剖析技术细节;若面向普通用户,则应采用通俗易懂的语言,着重阐述操作流程与功能应用1。
-
搭建清晰的文档结构:
- 拟定大纲:依据文档主题,梳理出涵盖引言、主体内容、结论等板块的清晰框架,各部分层层递进,逻辑连贯。例如,在编写软件使用手册时,可依次涵盖产品概述、安装步骤、功能模块详解、常见问题解答等章节1。
- 合理划分章节与段落:以模块化思维组织内容,每个章节聚焦一个核心主题,段落间过渡自然流畅,便于读者快速定位所需信息12。
-
确保内容准确与完整:
- 技术精准性:对涉及的技术概念、原理、流程等进行严谨的阐述与解释,杜绝模糊或错误表述。可通过引用权威资料、实际案例分析等方式增强内容的可信度1。
- 内容全面性:涵盖所有关键信息,避免重要细节缺失。例如,在硬件设备技术文档中,除了产品规格参数,还应包含组装指南、调试方法、维护保养要点等内容1。
-
优化语言表达与格式排版:
- 语言简洁明了:运用简洁、直白的语言风格,避免冗长复杂的句子与过多修饰词。多采用主动语态,使表述更具行动力12。
- 格式规范统一:建立统一的字体、字号、行距、编号等格式标准,善用图表(如流程图、示意图、表格等)直观呈现信息,增强文档的可读性与视觉美感12。
-
选择合适的工具和平台:建议使用可以被多人看到、可以被检索的知识库工具,如公司内的wiki或归属于组织的知识库。对于短时间多人协作的文档,可以选择在线多人协作工具如腾讯文档等3。
通过以上步骤和技巧,可以制作出一份高质量的技术文档,确保其清晰、准确、易读,从而有效传达技术信息并促进技术交流与合作