技术人员如何写好一篇高效的操作集成文档

背景

公司前端时间引入了xxl-job，是另外一个小组的小伙伴们经过调研、使用、上线整条链路，最终经历千辛万苦把这个定时任务组件给顺利推上线了，经历了一段时间的线上验证，稳定运行没有任何问题，接下来他们需要把这个组件推给其他小组去使用，最终使整个公司的定时任务统一规范，统一使用，然后他们准备了一篇wiki，也是基于此篇wiki，才有了这篇文章的产生

 

正文

很多程序员沉迷于代码，觉得写好代码就可以搞定一切，代码就是他的全世界，岂不知代码世界之外也有很多美好的东西，比如: 写写文档，记录一下感想。所以程序员写出来的文档都是让人抓耳挠腮，看一眼心中的火会一下子串起来，嘴上嘀咕一声: TMD, 这什么文档，让我怎么使用，怎么集成，怎么写，注意什么? 难道你趟过的坑还要让我再走一遍？

很多时候程序员都是觉得自我很聪明的人，也难怪，因为程序员中"秃顶"的最多，这就是聪明绝顶。题外话，回到正题，就是我们如何更好的写出一篇让人满意的文章呢？站在技术人的角度来说明这个事情，其他除外

第一: 把自己当白痴一样去写，不要觉得自己啥啥啥都明白了，别人也应该明白，不要用自己的要求去要求别人

第二: 梳理自己的逻辑重点，考虑如果是自己看这篇文章，会注意哪些东西

第三：按照这个文档操作，是否能解决99%的问题

之前我们开发完一个系统之后，都会写用户操作手册。用户对象就是公司非技术人员，如何让他们看着文档操作，达到他们想看的东西，此时操作手册基本上都是截图，截图，截图。图能胜过千言万语，比很长一段文字更能说明问题

 

针对公司推广一个插件给其他小组使用，提出以下几点：

1. 插件的版本统一化，使用的Pom.xml里面的依赖写清楚
2. 添加的配置类，配置类的代码，并说明此配置类的作用，以及需要注意的问题
3. 配置文件，不同的环境需要不同的信息配置，一定要说明: 线上、灰度、预发布、测试各个环境的配置不同之处
4. 其他说明(如: 启动时需要注意什么？如果自己集成时遇到的异常此时需要把异常贴上去，并说明如何解决，因为不同的人去用，肯定会遇到形形色色的问题，把问题写上去，并标明怎么解决，这样让人一目了然，也射给你过去了别人麻烦你)