编写文档就是对相关内容进行编辑、修改和调整。如果资金和时间都比较充足可以由专门的人员来做。能做出高品质的文档。
中文名
文档编写外文名
Documentation
定 义
文档编写是指可以进行编辑与修改
文档编写人员配备
编辑
1.文档编写者:实际编写文档内容的人。如果资金和时间都比较充足可以由专门的人员来做。能做出高品质的文档。但是这种情况在广大的中小项目中比较少。多种情况下,编写文档的人会是程序的设计或开发人员。他们熟悉项目,省去了培训的成本,但是工作性质的不同决定了他们一开始写出的文档品质相当的不高。对项目的过度熟悉让他们潜意识地觉得文档没有什么内容好写。
2.文档审查:负责文档的内容正确性,用语准确、简洁。说白了就是英语文档的语法、词汇检查。同时也许要负责文档基本样式的定制和进度的安排。不要以为英文文档才需要,就是中文文档,不同人写出来的风格也不一样。但是文档是要有统一的风格的,所以一定有人专门的人负责这个广义的风格。这个人最好有一定的计算机使用功底,不是随便一个英语好的就OK的。
3.技术支持:一般是兼职,要做的事实在不多,但是这部分的工作也是很重要的。主要包括如下的几个方面:
(1)负责HTML文档的模版。
(2)CSS的编写和维护:没有一个共享的CSS维护页面的样式可是很不专业的表现。
(3)CHM项目的维护:要有完整的目录和索引。
(4)程序与CHM的整合:当用户在程序的一个地方按F1时,要能打开CHM的相关主题页。
文档编写工具选择
编辑
1. HTML编辑工具:就是用什么软件写文档的问题。一直都是做.NET开发,所以选择HTML编辑大都在MS阵营里选。主要有以下几种HTML编辑器。
(1)Dreamweaver:做WEB开发的老大级产品。
(2)Visual Studio:如果用VS开发程序,那么写文档直接用VS打开HTML就可以了。
(3)Expression Web:Expression套装的重要组件,由FrontPage发展而来。良好的代码自动完成功能。Design界面等和VS的实在是很像,感觉很可能用了同一个内核。一个缺点就是不会监视文件的外部更改。这个东西是要买的,不买的话只有一个多月的试用期,如果不想花钱,而文档计划又要在一个月之内完成。用这个是很合适的。
(4)各种Office:比如Microsoft Office、Open Office等都可以用来编写HTML。也是最差之选。有了模版之后,用记事本也比这个强。生成的HTML有大量垃圾代码,没有CSS,多人编写时不便于merge。不到万不得已绝对不要用这个东西写HTML文档。用这个东西好处就是方便领导Review。加批注比较方便。而Open Office的优点就是免费。
2.文件管理平台:文档文件多了,写文档的人和审阅文件的人一起工作难免会有同步文件的问题。为了解决这个问题,可以用CVS,Source Safe,Perforce之类的源文件管理软件帮助维护文档文件。文件多,人也多的时候,这一点非常重要。
文档编写注意事项
编辑
1.由于是HTML文档,其中的Hyperlink是依赖于文件名的(程序员都知道,不过审阅文档的可不一定,一高兴把文件名改了不是玩的)。所以轻易不要改文件名。有哪些文档,都叫什么,最好写写之前确定下来。
2.如果使用HTML Help Workshop生成CHM,文件名不要有’&’等字符。不然会让链接失效。(发现有些MS软件的CHM文档是用GUID当文件名,感觉很不好维护,不知这个HTML是不是从别的文件生成的。)
3.每次开始写一种类型文档之前一定要有一个专门的会议确定要写什么,怎么写,详细到什么程序,以及文档的措辞,图片的选取等重要问题。如果时间充足,很有必要写一个文档的文档来进行规范化。不要因为所谓的时间紧为由,三言两语就打发人去开始写文档,一个新生写的文档一定不是你想要的文档。结果就是返工。而且即使都是老手,写得都对,但是一人一个写法,放一起还是不对。
4.确定版权信息。一般页脚都会有版权声明。
[1]
参考资料
1.
编写文档经验总结
.新浪网[引用日期2013-01-15]