技术文档总是令人头大,
一是文档内容可能不够全面,可读性差,可操作性差
二是不知该从何写起,在此简单总结一下之前的内容和思路:
目录
一.操作类、代码demo文档
-
此文档用于解决:xxxx
-
给出具体登录哪个机器/哪类机器,ssh登录还是通过堡垒机登录,或者其他登录方式
-
没有登录权限找谁开通
-
给出文字版操作命令,wiki code模式给出,文本模式格式有问题:这里不要截图,用户习惯从wiki粘贴命令再修改之后执行,当然也不要写一个有危险的命令,而是里面参数用test等字符代替)
-
给出操作命令正常返回内容,以及内容说明
-
给出操作命令异常返回内容,内容说明,如何处理,用户无法处理的联系谁,提供什么错误信息
-
整个操作流程必须经过文档编写者自己的验证,不要随便从网上找一个操作过程粘贴过来
-
超过4步的操作,要有简洁的操作流程图描述
-
复杂的操作流程/api,应该类比类似的其他用户常见系统/DB,对比进行描述,不要给用户罗列一堆名词
-
总结:标准化、可实际操作、系统化能列出1,2,3项而不是逻辑混乱,语言简洁可读性高不要罗列不需要的名词(给出用户熟悉的系统/DB类比)
二.技术介绍类文档
-
应用场景介绍:
-
概述:1,2句话就介绍清楚,不要罗列大量的用户未知名词、单词
-
或者直接给出所有需要用户知道的名词解释
-
给出应用的系统,App截图比较有说服力
-
描述查询场景,写入场景
-
给出数据量/请求量/P99. 等请求延时的大致范围
-
对比:和其他在应用方面类似的系统/DB进行对比:
- 数据类型支持哪些不支持哪些
- 支持哪几种api操作
- 数据导入导出是否有工具支持
- 扩容如何进行对用户是否有影响
- 底层支持的存储的数据量
- 一条数据最优大小
- 一次操作最优数据Size
- TTL
- 事务支持级别
- 其他独有特性:HBase支持动态列,如二级索引
-
然后给出一句话的总结:适合什么场景,不适合什么场景
-
最佳实践:
-
对应系统/App截图:给出对应系统截图
-
原来使用的什么方案,为什么现在选择这个新的方案
-
特性应用:给出此实践应用到了哪些特性
-
技术选型:给出特性是如何考虑,选择的?如果不使用这个特性会有什么问题,使用之后有什么对比的提升?(最好给出数字的对比)
-
架构介绍:
-
给出架构图:不要从网上随意找一个,也不要走用户的,请经过自己的验证以及是否符合下面要说的内容
-
节点类型:用户主要和那些节点交互,功能是?会涉及到性能瓶颈吗?需要用户怎么避免?
-
除了读写过程,一些主要的后台处理的介绍:比如:HBase的compact用来合并小文件,清理超期数据减少每次读取的压力。split分割大的分片为较小分片,避免分片太大影响读写性能
-
重要的功能点:比如Phoenix的二级索引是通过什么节点的什么特性进行的
-
存储简介:一致性属于什么级别
-
读写过程简介
-
给出简单的请求链路的图,中间涉及哪些组件,第1,2,3,4步在途中有箭头表示出来