文档要怎么写?

题记:今天立秋了,明天永远是美好的一天

场景

最近给运维人员写了一份部署三个项目的文档,由于系统需要和其他两个系统交互,所以在配置方面复杂了些,尤其是对xml文件地址配置这块,经常出问题。当基本功能实现的时候,给运维人员去部署的时候,写文档不单单是给别人写,更多的是给自己写。写的过程中思路清晰了,一切都会变得明朗起来,有一种山穷水复疑无路,柳暗花明又一村的感觉,并且一下子把需要大脑中记忆的这些事情全部转移到了文字上,一个字,舒服~,就像清理了电脑中的垃圾空间一样。

不过当我把写好的文档实际上去交给运维人员,运维人员需要根据文档去部署,去配置的时候,发现自己写的还是不够细致,有的地方自己能懂,但是他人却很难消化,并且还需要来问我。那些文档的时候要怎么写呢?大概总结如下,愿大家指教。

文档的本质?

文档不能光顾着结构清晰,文档好看,而是要去想用什么形式写更易懂,哪些地方不用详细,哪些地方必须详细,必须多说几句的,哪些地方是不容改变,哪些地方需要根据服务器地址来灵活改变的,等等。应该迎合阅读者的思维,理解过程来写,最好是能用图就先用图把大概的关系写出来。

文档面对的对象?

在下手写文档的时候,还是需要确定好文档是写给谁的,是针对哪个用户来写的文档,在一开始弄cas这块就要求写文档,当我在不知道具体是哪个用户使用的前提下写出的文档,对于运维人员来说根本就用不了,所以就废掉了,所以一定要针对的对象来写。

啥时需要些文档?

我认为我们既不能思想上全部文档化,因为写文档是一件耗时的事情,而且改动文档的版本也需要花费大量的时间,所以一定要斟酌哪些需要文档。我认为写文档的最终目的也是为了提高效率,减少了人与人之间沟通的时间,解放大脑,解放人力,从这个角度来衡量一件事情是否需要些文档。

不重视结构?重视结构?

虽然文档的结构样式是不必要的,就我们总是说一个人的外貌是不重要的,但是看到美女广大男士们还是垂涎欲滴的。所以对于勤劳的程序猿们来说,看一份爽爽的文档还是十分有必要的,从看文档的用户角度出发,怎么方便用户怎么来,结构的设置,排版设置,字体的设置,一段话是否表达了一个中心意思等。

大概的想到这些,望大家指教。O(∩_∩)O~

序:

生若夏花之绚烂 死若秋叶之静美

文档要怎么写?,布布扣,bubuko.com

时间: 2024-10-09 22:04:25

文档要怎么写?的相关文章

接口文档要如何写

一个简单的接口文档,写完给组长看后,发现漏洞百出.下面总结一下写文档需要注意事项:        封皮 封面最好是本公司规定的封面,有logo,内容标题,版本号,公司名称,文档产生日期.(错误地方在于,文档的标题要和页眉中的标题一致)        修订历史 表格形式较好些.包括,版本,修订说明,修订日期,修订人,审核时间审核人.(我错误的地方在于,表格中其他空白表格没有居中)        接口信息 接口调用方式,是post方式还是get方式,接口地址,别人需要线上的哪个地址就写哪个.(自己提

设计文档要如何写——转

一份设计文档的结构大概可以分成Background项目背景.Schedule排期.History版本历史记录.Information Architecture信息架构分析(包括Site Map.Experience Map.Flow等).Framework框架设计.Wireframe线框图和Mockup视觉稿等.取决于实际项目的情况,部分内容可以省略,也可以加入更多,比如Storyboard故事板,Prototype可交互原型等. 在过去,我一度没有什么规范的设计文档写作习惯,用纸笔画完Info

软件工程文档设计中的基本要求:关于每个文档究竟该写什么

首先看软件需求分析 需求分析阶段的任务分为四个阶段:需求获取,需求分析,需求定义,需求验证 需求获取这部分比较模糊,应该也是比较杂,比较灵活的一部分,先来个大概的功能叙述,然后将需求一项一项地列出来. 需求分析这部分要求对前面的需求进行规范 1,对每项需求给出清楚的描述 2,要求描述没有歧义 3,各项需求之间不能存在矛盾,软件需求和实际需求不能矛盾 4,对需求实现的可行性进行分析 4.1 技术可行性:在现有条件和环境技术下考虑 4.2经济可能性:小项目一般不考虑这个 4.3社会可能性:考虑知识产

为什么要写设计文档

日趋一日,程序员能够在更少的时间内完成更多的事情.使用今日的高级编程语言,开发环境,工具和“快速应用开发”思想,程序员和经理都已经习惯于急速的开发周期.今日的程序员更倾向于直接跳入到编码之中,害怕花费在非编码工作中的每一小时,都会导致项目截止日期前的周末多加一个小时班. 编码之前做设计这一过程已经变得过时了,将设计文档化就更罕见了.很多程序员从来没有写过设计文档,面对要写设计文档这一想法都畏缩不前.即使被要求写,通常来说也只是产出了一大堆的交互图和类图,这些图表大多没有表达程序员在设计阶段的思考

从程序员到项目经理(29):怎样写文档【转载】

在软件项目中,文档既是一项的重要成果,也是项目管 理的有力工具.通过文档,可以稳定.明确的传达信息,实现项目内的有效沟通.所以写文档对项目经理来说,是一项必备的技能. 然而很多项目经理害怕写文档,似乎这是一个很麻烦. 很困难的工作.其实会不会写文档,只是一种外在的表现,通过一个人写文档的情况,可以看出他对工作的理解程度,发现潜在的问题和风险.一个合格的项目经理,不但不会怕写文档, 而且会觉得这是一件简单.很自然的情,就像一个人吃饭.喝水一样,何难之有? (本人拙作<程序员第二步 -从程序员到项目

PRD文档怎么写

昨天学习PMP的相关文档,正好看到里面讲的PRD文档是怎么写的 就把一些学习过程,思维方式,还有用到的工具给记录下来 方便自己以后需要的时候,再去查阅,再读这个教程的时候,我顺便用脑图画了一下 脑图工具是在线的百度脑图 首先什么是PRD文档,与需求人员交流我发现,有时候他们并不会先将自己的思想加工成条理清晰的语言,再去表达. 而是一上来就说细节,要做成什么样,而对于测试和开发人员,没有场景带入 不知道你这个功能,在业务场景里面,所处的位置,起到的作用 就没发很好去实现和测试,而会加入很多自己的想

分享一下自己写的Python 3的各种PDF文档【花了半年时间那】

这些文档花了我半年的时间去整理,由于是第一次进行整理,希望帮助后来者少走弯路,毕竟是第一次整理,哪些地方不到位,希望大家和我练习,我们一起把它做好,下面就直接给出下载地址了,都是免积分的下载奥,因此,想怎么下就怎么下. 首先就是这个,它介绍了Python的基础语法,个人感觉还是蛮精炼的,下面是在CSDN的下载地址:python基础语法下载,如果不能下载,大家可以在浏览器中输入如下地址进行下载:http://download.csdn.net/detail/xinguimeng/7643003 然

document.write 向文档中写内容,包括文本、脚本、元素之类的,但是它在什么时候执行不会覆盖当前页面内容尼?

当你打开一个页面,浏览器会 调用 document.open() 打开文档 document.write(...) 将下载到的网页内容写入文档 所有内容写完了,就调用 document.close() 触发 dom ready 事件(DOMContentReady) 所以你如果在第3步之前 document.write(1) 那么你就直接追加内容到当前位置,如果你在第3步之后 document.write(),那么由于 document 已经 close 了,所以必须重新 document.op

程序员要双管齐下写好代码和写好文档

有一个问题就是程序员为什么不喜欢写文档,这个问题是一直存在的,不管怎么说,文档绝对是程序员最大的软肋.一些被称之为高手的程序员,往往是文档方面的低能儿.不管这个程序员是在大公司.还在小公司.不管程序是写文档的.还是不写文档的,大部分程序员在内心深处中是不愿意写文档的.  天下的怪事特别多,有时让人不能理解.程序员一般不愿意写文档,但是程序员却喜欢看别人的文档.即使写了文档,程序员一般不会把所有功能都写入文档,却抱怨别人文档有的功能没有说明.即使写了某段文档,程序员一般不不想把文档写的很详细,却抱