写技术文档需要注意什么
技术文档总是令人头大，
一是文档内容可能不够全面，可读性差，可操作性差
二是不知该从何写起，在此简单总结一下之前的内容和思路：
目录
一.操作类、代码demo文档
二.技术介绍类文档
一.操作类、代码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步在途中有箭头表示出来
写技术文档需要注意什么相关推荐
- 不写技术文档是个什么梗
写文档在工作中很常见了,正规的公司都有文档,除非是很简单的东西. 文档用来给新人或不熟悉的人的看,出需求也要文档.只凭笔在本子上划几下不能让人懂. 凡是稍微复杂的东西一定用文档梳理流程,有的还有流程图 ...
- java开发文档怎么写_程序员该不该写技术文档，怎么写文档，易懂又能提升自己...
最近公司项目的调用量突然涨了一大波,很多系统都纷纷扛不住了,于是需要对系统进行优化,系统优化的第一步,便是梳理业务! 在这个过程中,经常出现了这样一些情况,发现数据库的某些字段,没有注释,也没有一定的 ...
- 优秀程序猿写技术文档的正确姿势
一.背景 写文档是程序猿进阶的一个必要步骤之一. 文档写的清楚,思路就更加清晰,也会让同事高看你一眼,多梳理业务也有很大帮助. 产品经理对需求文档基本是驾轻就熟信手拈来,但是大多数程序猿写技术文档却显 ...
- android技术文档怎么写,技术文档编写指南
技术文档编写指南 首先请阅读文案风格指南 ##学习产品使用方式 最重要的必备的条件就是: 一定要亲自使用这个产品,至少是一遍通顺的流程要走完,不要求每一个接口都一定使用过,但是一个完整的功能片段是使用 ...
- 开发人员(程序员)怎么写技术文档
声明:本篇文章不带任何软文及打广告性质,该用的工具还得用!!! 今天,在找springboot资料没发现好的中文文档,即使有springboot某些框架的使用博客,也都是碎片化的,对小白极度不友好,连 ...
- 01_从此哥看破红尘，要开始习惯写技术文档了。
此文章无内容,但是!随着哥技术的长进,哥要记录着走过的每一步.for this go!
- 如何写出优秀的技术文档？
大家好,我是小枣君. 鲜枣课堂自从2017年5月开始正式创立,迄今已有3年多的时间.这一期间,我们的内容一直都坚持以技术类科普文章为主,输出了大约400多篇原创.其中绝大部分,都是我写的. 我的想法比 ...
- 【资源推荐】良心之作！超过 10000+ 的互联网团队正在使用的在线 API 文档、技术文档工具...
搞开发的同学都知道一个好的 API 文档是有多重要! 每当接手一个别人开发好的项目,看着那些没有注释的代码,真的头大. 程序员都很希望别人能写技术文档,因为可以提高自己开发的效率,而往往自己却很不希望 ...
- VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客
前言: VuePress是尤大为了支持 Vue 及其子项目的文档需求而写的一个项目,VuePress界面十分简洁,并且非常容易上手,一个小时就可以将项目架构搭好.现在已经有很多这种类型的文档,如果你有 ...
最新文章
- html5 form表单,html5 教程
- YUM部署高版本LNMP环境
- GPS服务端解析程序编写日记之--vs2010中多种语言开发及调试的若干注意事项
- python 生成器笔记
- LCFinder 0.3.0 Beta 发布，图像标注与目标检测工具
- python 输入华氏温度f_如何用 python编写华氏摄氏度的相互转换？
- C++之指针探究(十五)：回调函数应用之qsort排序
- 美国河流出现神奇冰盘 顺着水流不断旋转
- Interop type 'jmail.POP3Class' cannot be embedded. Use the applicable interface instead.
- 斐波那契数列的量化分析
- 结合CDIB类，对图像的打开、显示、保存
- stringstream 使用方法
- 网络流专题（最大流与费用流）例题总结
- 【自动驾驶轨迹规划之RRT算法】
- wlan消失 网络适配器文件夹空了 设备管理器黄色感叹号 wifi那里看不到任何WiFi解决
- 信息安全管理——仿射密码破解
- SpringBoot爬虫
- 【uniapp滚动穿透】 在u-modal中使用scroll-view底下主页面会跟随滚动
- Java 确定线程池中工作线程数的大小
- mysql 截取括号内字符串_Mysql字符串截取_获取指定字符串中的数据