写技术文档需要注意什么

技术文档总是令人头大，

一是文档内容可能不够全面，可读性差，可操作性差

二是不知该从何写起，在此简单总结一下之前的内容和思路：

 

目录

一.操作类、代码demo文档

二.技术介绍类文档

---

一.操作类、代码demo文档

1. 此文档用于解决：xxxx

2. 给出具体登录哪个机器/哪类机器，ssh登录还是通过堡垒机登录，或者其他登录方式

3. 没有登录权限找谁开通

4. 给出文字版操作命令,wiki code模式给出，文本模式格式有问题：这里不要截图，用户习惯从wiki粘贴命令再修改之后执行，当然也不要写一个有危险的命令，而是里面参数用test等字符代替）

5. 给出操作命令正常返回内容，以及内容说明

6. 给出操作命令异常返回内容，内容说明，如何处理，用户无法处理的联系谁，提供什么错误信息

7. 整个操作流程必须经过文档编写者自己的验证，不要随便从网上找一个操作过程粘贴过来

8. 超过4步的操作，要有简洁的操作流程图描述

9. 复杂的操作流程/api，应该类比类似的其他用户常见系统/DB，对比进行描述，不要给用户罗列一堆名词

10. 总结：标准化、可实际操作、系统化能列出1，2，3项而不是逻辑混乱，语言简洁可读性高不要罗列不需要的名词（给出用户熟悉的系统/DB类比）

 

 

 

二.技术介绍类文档

 

1. 应用场景介绍：

2. 概述：1,2句话就介绍清楚，不要罗列大量的用户未知名词、单词

3. 或者直接给出所有需要用户知道的名词解释

4. 给出应用的系统,App截图比较有说服力

5. 描述查询场景，写入场景

6. 给出数据量/请求量/P99. 等请求延时的大致范围

7. 对比：和其他在应用方面类似的系统/DB进行对比:

   1. 数据类型支持哪些不支持哪些
   2. 支持哪几种api操作
   3. 数据导入导出是否有工具支持
   4. 扩容如何进行对用户是否有影响
   5. 底层支持的存储的数据量
   6. 一条数据最优大小
   7. 一次操作最优数据Size
   8. TTL
   9. 事务支持级别
   10. 其他独有特性：HBase支持动态列，如二级索引

8. 然后给出一句话的总结：适合什么场景，不适合什么场景

9. 最佳实践：

10. 对应系统/App截图：给出对应系统截图

11. 原来使用的什么方案，为什么现在选择这个新的方案

12. 特性应用：给出此实践应用到了哪些特性

13. 技术选型：给出特性是如何考虑，选择的？如果不使用这个特性会有什么问题，使用之后有什么对比的提升？（最好给出数字的对比）

14. 架构介绍：

15. 给出架构图:不要从网上随意找一个，也不要走用户的，请经过自己的验证以及是否符合下面要说的内容

16. 节点类型：用户主要和那些节点交互，功能是？会涉及到性能瓶颈吗？需要用户怎么避免？

17. 除了读写过程，一些主要的后台处理的介绍：比如：HBase的compact用来合并小文件，清理超期数据减少每次读取的压力。split分割大的分片为较小分片，避免分片太大影响读写性能

18. 重要的功能点：比如Phoenix的二级索引是通过什么节点的什么特性进行的

19. 存储简介：一致性属于什么级别

20. 读写过程简介

21. 给出简单的请求链路的图，中间涉及哪些组件，第1，2，3，4步在途中有箭头表示出来