文档规范

项目管理文档的写作规范 1.        文档设计的重要意义 1．对整个公司团队的意义：软件的生产已经从手工艺的开发方式发展到工业化的生产方式，文档是整个公司开发平台建设的基础，而平台建设是公司正规化、规模化及可持续发展的标志。 2．对设计者本身的好处：a.软件文档的编制，使得开发人员对各个阶段都进行周密思考，全盘权衡，从而减少返工，提高开发效率；b.文档是开发人员工作成果和工作结果的标志。 3．对直接用户和潜在用户的意义：a. 好的用户文档能反映出产品的档次，增加用户对产品的依赖；b. 便于潜在用户更好的了解产品，为他们选购符合自己需要的产品提供依据。 4．对公司其它设计人员的好处：使开发工作建立在共享公司成果的基础上，使开发活动有效、有序和科学化。 文档设计工作既然如此重要，因而每一个软、硬件设计工程师没有理由不做好这一工作，任何不习惯写或不感兴趣，不认真对待这一工作的思想都只能是借口，因此开发工程师必须完成文档的设计工作，不写文档者公司将立即淘汰。 2.        公司文档的分类（待补充） 1．开发文档        产品设计文档；特定硬件或软件任务文档（某个特定专题的设计文档如串行通讯的可靠性，IC卡读写程序，I2C总线上的数据发送与接收程序等设计文档）。 2．用户文档        软件需求说明书；产品使用说明书（或用户手册）；产品宣传演示文档；器件文档（包括器件原始文档、生产厂商器件使用手册及有关应用的原文及中文资料和器件应用或演示文档）。 3．管理文档        项目开发计划；测试计划及报告；项目开发总结。 3.        文档的创作规范 之所以称之为创作，是因为文档不是随随便便就能写好的，需要付出辛勤和努力，需要热情，需要创造！ (1) 器件应用文档的写作规范 A. 总原则 器件的组成、结构原理及各种指标用简练的语言辅以综合性表格加以描述；器件的突出特点及重要功能作详细的叙述并给出应用实例（包括电路原理及接口软件）。 B．文档的组成 1．摘要  简要叙述本篇文档的基本内容，以便使用者对文档有一个清晰的概括了解，便于其阅读和使用。 2．器件概述  对器件的主要特点、主要性能、主要指标和主要的应用场合作一个概括性说明，以便使用者对该器件有一个全面的认识。 3．器件的结构与原理  该部分描述器件的基本组成，包括管脚排列及管脚描述、内部电路、内部寄存器的描述（一般配以图表）以及各种功能的描述。 4．器件应用电路及接口软件的设计  给出应用电路和具有详细标注的软件清单，必要时对硬件电路及软件设计做出描述并给出测试说明和注意事项。这部分是本篇文档的重点。 5．器件应用举例   用一个或一个以上的具体实例说明器件的应用，该部分可以和第4部分的内容合起来写，亦可单独叙述。 6．附录  包括a.参考资料；b.软件设计中应用的程序模块清单； c.其它必要的资料。 (2) 产品开发文档的写作规范 A．        总原则 开发文档是公司的内部设计资料，是公司开发平台的重要支柱。因此，开发文档的写作必须遵循详细、真实和全面的原则。 B．文档的组成 1．摘要  简要叙述本篇文档的基本内容，以便使用者对文档有一个清晰的概括了解，便于其阅读和使用。 2．设计方案/设计思想  此乃开发文档的精华之所在，能够体现开发者的水平和设计风格，该部分内容应包括系统框图和重要的算法分析。 3．基本硬件设计与分析  该部分描述开发项目的硬件设计思想，应给出具体的设计说明和详细的数据资料、表格和原理图。 4．基本软件设计与分析  该部分描述开发项目的软件设计思想，应给出具体的设计说明和系统框图及原程序清单。应遵循模块化的设计风格分别对各模块进行分析。 5．测试说明及总结  说明产品开发完成后的测试及使用情况并说明产品今后需改进或完善的地方。 6．附录  包括a.参考资料；b.软件设计中应用的程序模块清单；c.其它必要的资料。 4.  文档的写作格式 公司所有文档统一使用Word排版，页面应当设置如下：纸型为A4，页边距规格为：上下各2.54cm，左右各3.17cm，装订线0cm，页眉1.5cm，页脚1.75cm。文档内容的排版格式如下（除特别说明外，中文用宋体，英文字体用Times New Roman）。 文档标题 •  3号黑体，居中，上下各空1行。如标题较长，可使用小3号字。 正文 •  中文用小5号宋体，44行，46列。 •  英文及 数字 用小5号Times New Roman。 •  正文中的程序用小5号字。程序格式应当整齐、规范。 •  正文中的1级标题用小4号黑体，占2行，顶格。2级标题用5号黑体。3级及以下标题使用小5 号黑体。 •  公式、图和表的编号要协调一致，按章编号，详细要求见后面的图和表要求。 •  使用术语要全书一致，图文表一致。外文单词是全部大写、首字母大写，还是全部小写，应遵循 习惯用法，尽量全书统一，图文表一致。 •  正文中层次不宜过多，可仅设章、节、小节、条、目等几个层次， 要有一定的编列统一格式。推 荐采用以下2种编排格式：   第1种           第2种 第1章     1.1     1.1.1     1.     (1) ① 1   1.1   1.1.1    1.    (1) ① •  每层次的标题由词组或短语组成，要简短明确，题末不带标点。同一层次标题在语法结构上应尽 量对等。同一层次标题语法结构上应尽量对等。 •  文中的操作步骤尽量统一用（1），（2）...或①,②…及再下的层次编号。 •  文中并列内容可用“●”，“◆”，“•”等项目编号列出，要尽可能做到全书统一。如有再下一层次 的并列内容，可用另一种项目符号。注意要易于区分层次的高低。 •  文中层次段落的缩进要遵守层层递进的原则，要特别注意用准确的顺序编号和段落缩进来表示层 次关系。同层次段落的缩进全书要统一。 •  文中不要用Ⅰ，Ⅱ，Ⅲ或a, b, c…作为顺序编号，也不要用一，二，三及（一），（二），（三）… 作为顺序编号。 •  不能出现孤立的编号。例如， 不能出现2.2.1， 而无2.1.2等后续编号的情况。如确实需要该 标题， 可采用不带编号标志的标题，字体字号与同等层次标题相同。 •  文中提到层次名时要准确对应，如“第2章”，“2.2节”，“2.2.1小节”等。 •  正文中的公式按章统一编号。编号放在公式右侧， 如第三章的公式编号为： （3-1）, （3-2）， （3-3）……。 图     •  每一个图都要有图题。 图中有（a）和（b）子图时，子图也要有子图题。 •  每一章的图统一排号， 如第3章的图用： 图3.1, 图3.2, 或图3-1, 图3-2。 •  图号和图题位于图的正下方。图题由词组或短语组成，要简短明确，题末不带标点。前后图的图 题不应雷同。 •  插图中的文字和线宽要求（屏幕图除外）： -        文字为小5号, 汉字用宋体，英文及数字用Time New Roman。如果空间不够，个别文字可用更小字体。 -        图中粗线粗细b的范围为： b=0.25-0.7 mm;  细线粗细为b/2，不得小于0.1mm。 -        图中一般情况下，主线用粗线， 辅线用较细的线。 •  图中的曲线要光滑，斜线不能有锯齿。文字的分辨率要高。 •  书中所有图要随文排，图文呼应。即要先有文字叙述（先提到图）, 后见相应的图。 •  图不能跨大节(即1.1节, 2.3节), 尽量不要跨小节(即1.1.1小节, 2.3.4小节)。 •  从PDF文件中取图，建议使用AdobeIllustrator，将取出的图存为.wmf文件以保证高分辨率。 •  对于器件文档，图中的英文应尽量翻译成中文。 •  不要用WINDOW 下或word的画板画图。此两个文件画的图文字分辨率差，斜线和弧线有锯齿。 •  在整个文档内，图的大小和比例要协调，紧凑。 表格 •  每一个表都要有表题。 •  每一章的表统一排号， 如第3章的表用： 表3.1, 表3.2, 或表3-1, 表3-2。 •  表号和表题位于表的正上方。表题由词组或短语组成，要简短明确，题末不带标点。前后表的表 题不应雷同。表题字体采用小5号黑体。 •  表内文字采用小5号，如排不下则使用6号字。 •  表格的绘制应遵循简洁、整齐的原则，避免使用复杂的格式。表格边框不应超出文档页面边界。     •  要先见文, 后见表, 即先在文中提到表, 再在其后见表。 •  表不能跨大节(即1.1节, 2.3节), 尽量不要跨小节(即1.1.1小节, 2.3.4小节)。 文后部分 附录应提供正文中部分内容的详尽推导、证明，以及有关数据、曲线或其他辅助住材料。附录应设标题，与正文有呼应。编写格式及图、表、式的要求同正文。