题记:今天立秋了,明天永远是美好的一天
场景
最近给运维人员写了一份部署三个项目的文档,由于系统需要和其他两个系统交互,所以在配置方面复杂了些,尤其是对xml文件地址配置这块,经常出问题。当基本功能实现的时候,给运维人员去部署的时候,写文档不单单是给别人写,更多的是给自己写。写的过程中思路清晰了,一切都会变得明朗起来,有一种山穷水复疑无路,柳暗花明又一村的感觉,并且一下子把需要大脑中记忆的这些事情全部转移到了文字上,一个字,舒服~,就像清理了电脑中的垃圾空间一样。
不过当我把写好的文档实际上去交给运维人员,运维人员需要根据文档去部署,去配置的时候,发现自己写的还是不够细致,有的地方自己能懂,但是他人却很难消化,并且还需要来问我。那些文档的时候要怎么写呢?大概总结如下,愿大家指教。
文档的本质?
文档不能光顾着结构清晰,文档好看,而是要去想用什么形式写更易懂,哪些地方不用详细,哪些地方必须详细,必须多说几句的,哪些地方是不容改变,哪些地方需要根据服务器地址来灵活改变的,等等。应该迎合阅读者的思维,理解过程来写,最好是能用图就先用图把大概的关系写出来。
文档面对的对象?
在下手写文档的时候,还是需要确定好文档是写给谁的,是针对哪个用户来写的文档,在一开始弄cas这块就要求写文档,当我在不知道具体是哪个用户使用的前提下写出的文档,对于运维人员来说根本就用不了,所以就废掉了,所以一定要针对的对象来写。
啥时需要些文档?
我认为我们既不能思想上全部文档化,因为写文档是一件耗时的事情,而且改动文档的版本也需要花费大量的时间,所以一定要斟酌哪些需要文档。我认为写文档的最终目的也是为了提高效率,减少了人与人之间沟通的时间,解放大脑,解放人力,从这个角度来衡量一件事情是否需要些文档。
不重视结构?重视结构?
虽然文档的结构样式是不必要的,就我们总是说一个人的外貌是不重要的,但是看到美女广大男士们还是垂涎欲滴的。所以对于勤劳的程序猿们来说,看一份爽爽的文档还是十分有必要的,从看文档的用户角度出发,怎么方便用户怎么来,结构的设置,排版设置,字体的设置,一段话是否表达了一个中心意思等。
大概的想到这些,望大家指教。O(∩_∩)O~
序:
生若夏花之绚烂 死若秋叶之静美