当前位置:首页 > 嵌入式培训 > 嵌入式学习 > 讲师博文 > 如何写文档

如何写文档 时间:2018-09-20      来源:未知

文档的反复是很正常的。不仅如此,不得不承认写文档和看文档是一件非常让人反感的事情,但是这件事情的重要性甚至超过了算法的研究本身,希望大家能够引起重视。在大型的项目管理体系中,文档的工作要占到70%的时间。当然,多数情况下我们开发的文档只是文档体系中的一小部分。

开发人员在写文档的时候往往会略去一些自己认为“顺利成章”的事情,而这些事情中的很多往往会令看文档的人感到困惑,这是一切文档工作失误的根本原因。所以,要掌握“从读者的角度”去写文档的方法。我始终认为,文档的格式虽然重要,但是把事情本身说清楚才是文档的目的,所以目前不对文档的格式做具体的要求。但是基本的几件事情要作为文档开发过程中的基本原则提出:

1)参考文献:应该尽可能多地,不遗漏地给出参考文献,但这并不等于参考文献中论述过的内容就可以在文档中省略。一般地,我们的原则是,对于参考文献提到的部分给出简明但是完整(二者相较,完整更为重要)的论述,然后在后附上参考文献。更进一步,参考文献应当打包附在文档的载体上,因为往往查找这些参考文献有时是很困难的。

2)图表和公式:图和公式作为“把事情 本身说清楚”的重要手段,应当大限度地为这个目的而服务,所以,和这个目的无关的东西应当尽可能地去掉,从而使读者可以一目了然。对图来说,应当为其目的专门绘制,而不是随便抓来一副包罗万象的图。对公式来说,应当针对要说明的内容的特点给出关键的公式,大段的公式推导应当作为附录。所有的绘图好能够 把绘图的原始文件打包附在文档的载体上,以便后来人进行修改。(Visio绘制的图在Word里可以直接编辑,但是往往就会出问题,所以也要附上原图)。

3) 文档的论述顺序:把所有的事情都说清楚,只是文档的第一步。更为重要的目的是让读者能够通过这份文档了解设计。为了方便读者,一个很重要的原则就是让读者可以“顺序”地阅读文档。读者在阅读文档的时候,很反感的一件事情就是要把文档前前后后翻来翻去。我们应当从文档的段落安排和论述风格上做到这一点,如果有需要读者“前前后后翻来翻去”的地方,一定要用醒目的方式注明。这一点不仅在文档的撰写工作中是重要的,甚至在程序的书写中也是重要的。

4) 写文档所采用的语言:应当首先采用自己熟悉的语言,然后相应地翻译为英文。在文档工作的实践中发现,如果一上来就采用自己不熟悉的语言,文档的开发人员往往会自觉或不自觉地“遗漏”掉一些论述起来比较复杂的内容。而审查文档的人也几乎不会针对于这些提出异议。这是非常危险的,为项目日后的维护和升级埋下了失败的种子。这个问题上,我们宁可丧失时间,也不愿意丧失一篇完整并且准确的文档。

上一篇:使用unix域套接字在进程之间传递文件描述符

下一篇:印制电路板(PCB)设计原则和抗干扰措施

热点文章推荐
华清学员就业榜单
高薪学员经验分享
热点新闻推荐
前台专线:010-82525158 企业培训洽谈专线:010-82525379 院校合作洽谈专线:010-82525379 Copyright © 2004-2022 北京华清远见科技集团有限公司 版权所有 ,京ICP备16055225号-5京公海网安备11010802025203号

回到顶部