项目文档编写规范与代码规范.doc
《项目文档编写规范与代码规范.doc》由会员分享,可在线阅读,更多相关《项目文档编写规范与代码规范.doc(25页珍藏版)》请在得力文库 - 分享文档赚钱的网站上搜索。
1、项目文档编写规范与代码规范往往越是规模大的公司,其项目工作中的每一个环节都有相应的规范进行管理,这些规范都是都前辈呕心沥血,披荆斩棘所获的的经验总结,而非普通文书工作者的推猜可得。 当然,如果刚刚创业起步的小公司如能更早的抓住项目规范、文档规范,更是使公司发展或者比大公司更大的推动力。 做文档应当十分注意细节问题,可以文档的细节规范决定文档的成败,正所谓细节决定成败。 1. 首先,绝对不允许有错别字。 2. 文档标题:命名标准为:客户公司名称+项目名称+版本号。(公司采编项目_V1.0 )。 3. 文档属性:打开word文档文件属性 (标题、作者、单位)。 4. 首页:文档标题,客户公司和实施
2、公司LOGO,左下角标注(实施公司名,作者,更新时间,版本,文档编号)。 5.文档管理:修改记录,审阅记录,分发记录,致被分发者。 6.目录:动态更新目录,任何栏目修改都要及时更新。 7. 项目编号:整个项目编号撑起了整篇文档的栏目构架,在视图文档构架图中应可以看清这个脉络。 8. 文档字体:文档的项目编号、正文、注释 都应有相应的字体大小。 9. 图片表格:每个图片和表格都必须要编号。 10. 段落:段落的之间的行距,是否空行,紧密程度应当十分注意,影响整体美观。 11. 页眉和页脚:页眉,左边是实施公司LOGO,右边是文档标题;页脚,左边有公司名及版权声明。拥有准确技术文档不仅对于公司是非
3、常有益处,而且也能够让客户从中受益。由于产品如何使用在某种程度上是要依赖技术文档来进行说明,因此技术文档必须十分准确可靠。使用不准确和已经过时技术文档对于公司发展也会产生一定阻碍,同样,它也会对公司客户们产生消极影响。一旦客户发现在他们使用产品时候遇到了问题,却不能通过求助于伴随产品技术文档手段进行解决时候,客户们就会对这种产品产生怀疑乃至于失去信心,那么,公司信誉和利益自然而然就会受到损害。这就是不准确和过时技术文档给我们带来危害。缺乏准确性以及内容晦涩难懂都会让开发新手以及其他一些技术工作者们对这些技术文档敬而远之,从而不利于他们学习和掌握。在本篇文章中,我们要讨论就是如何在你开发小组中编
4、写出准确而且易于掌握技术文档。技巧一:制定出一个技术评价核对表许多程序开发设计者以及管理者都缺乏从技术上评价一个文档经验。这里有一些方法可以提高这些技术文档准确性:把注意力集中于技术事实上,这样能够核实这些技术是作为技术文档而被编写出来。技术评论工作并不等同于一般编辑工作。一定要从技术上核实,在技术文档里编写程序与步骤准确性。一定要从技术上核实,在技术文档中使用图片捕捉准确性。技巧二:一定要在技术文档编写过程中明确责任技术文档编写不一个原因常常是由于对它不够重视。这是由于在编写技术文档时候,没有十分明确各种责任。因此,一定要在技术文档编写过程中明确责任,这些方法包括:在技术文档中加入作者以及相
5、关人员姓名。一些公司可能有规定,禁止出现员工姓名,但是在技术文档中包含作者以及相关人士姓名做法能够促进这些内部员工之间交流。对于外部文档使用者,比如为商业现货软件编写用户指南,可以加入作者以及相关人员姓名,用以明确和承认他们对开发所做工作和贡献。把文档技术评论作为提供给开发设计人员年度评论一部分。在项目计划中指派专人负责技术评论工作。技巧三:增加技术文档编写者准确性 由于技术文档编写者在许多公司内都是非常主观一个职位,并且编写技术文档也是他们最主要职责,因此做这些工作人都必须与他们所编写技术文档准确性有着直接利害关系。 字串7管理人员应该为技术文档编写者设置适当技术准确级别,并要求他们把准确性
6、保持在这一范围之内。由于一些技术文档编写者对于提升自己对于技术理解总是不太积极主动,因此,增加他们责任让他们面对更多压力对项目里每一个人来说都是有处。如果一个技术文档编写者无法达到更高标准,那么你就需要重新审视一下你技术文档编写者是否能够满足你们团队战略要求,是否能够满足客户们需要呢?为了帮助技术文档编写者,你需要让他们对于具体技术有着更深层次认识,因此,作为管理者,你应该:让技术文档编写者多参加有关产品设计与开发小组会议。让技术文档编写者参与到技术要求、功能规范以及设计方案开发工作中去。把技术文档编写者包括进开发小组邮件列表中去。这技术文档编写周期,把产品在公司内部进行发布。技术文档编写者很
7、容易变得非常封闭,但是如果把产品在内部首先发布一下,那么就能够给开发人员以及项目管理人员提供一种新途径来了解以前可能并不容易了解情况。鼓励技术文档编写者更多了解有关产品背后所包含各种技术。举个例子来说,如果你开发基于Java语言应用软件,那么,就应该鼓励技术文档编写者多多了解Java编程语言,并且尽量让他们能够流畅掌握这门编程语言。技巧四:设置任务优先次序通常情况下,主要开发设计人员脑海中包含着有关整个项目信息,而且,有时候还会同时考虑许多其它项目。即使他或者她日程安排已经非常紧张,但是,他们脑海中产品信息对于确保技术文档编写准确性来说是非常重要。当前形势让我们不得不以更少资源完成更多任务,而
8、作为开发设计人员,由于他们工作特殊性,这些人总是处于紧张而繁忙状态下。下面是一些技巧,可以帮助你从这些忙碌开发设计人员哪里获得你所需要信息,并且保证能让他们知识给技术文档编写带来处:不要让他们从头至尾审阅技术文档。 和技术文档编写者一起确定哪些部分必须让开发设计人员进行审阅。与他们一起利用大段完整时间来审阅技术文档。如果技术文档审阅者时间表安排得很紧,那么就给他提供一个具体列表,在其中明确哪些部分你需要他进行审阅。并且保证让小组内其他成员完成剩余部分审阅工作。技术文档中与审阅者专业技术领域直接相关部分绝对是需要他进行仔细审阅。更完成审阅工作充分有效完成技术文档审阅工作不仅会让外部用户,也会让内
9、部用户从中受益。但是,经常会有技术人员认为做这样工作是没有多大意义,那么,作为管理者就面对着这样一种挑战,就是要在整个审阅过程中设置优先次序从而保证为开发工作所做出努力获得成功。软件测试文档的流程 整个测试过程的文档。先写测试策略,测试策略包括:所要测试的范围,阶段的划分,已经每个阶段完成的标准;然后是书写测试计划,测试计划主要包括:谁来做,在哪里做,什么时间做,为什么做,和做什么;接着书写测试方案,如果比较简单的就不需要书写测试方案,直接在测试计划里就可以写明白,比较复杂的才写测试方案,测试方案是书写专项测试计划的,以保证专项测试完成;再写测试用例,也就是说该怎么做;测试执行后生成测试记录和
10、缺陷报告;测试结束后,生成测试报告。文档资料规范要求 一、资料格式要求1、纸型所有纸质文字资料除个别表格必须使用A3纸以外,其余一律用A4复印纸。2、封面文件必须按国家行政机关公文格式执行。纸质材料一般不加封面,确需加封面的材料可以加上,如规章制度、材料汇编等。封面可使用必要的文字和徽标,但不宜使用花边和其它图案。加封面的材料同时应加封底。3、文档(1)页面设置:页面、版式原则上使用软件默认设置,即:上2.54cm,下2.54cm,页眉1.5cm,页脚1.75cm,左右可调整为2.5cm,页码统一在右下角,纵向排列的每页行数控制在44-48行之间,横向排列的每页行数控制在26-29行之间。为避
11、免最后一页只是几行占一页的现象,可适当收缩行距,使文件成为几张整页,但收缩行距不宜小于20磅。(2)标题标题用宋体三号字加粗,顶行。副标题居中排列,使用4号仿宋,但不与正文字体重复,破折号占2格。(3)正文用仿宋体四号字正文内1级标题文字使用4号仿宋、加粗,2级标题使用楷体(或华文楷体),3级标题使用仿宋体,4级标题使用仿宋体。标题单独成行时,均无需标点。不提倡正文内使用加粗或艺术字体,如行书、隶书、魏书、细圆体、综艺体、琥珀体等,以保持公文严肃、文面整洁。(4)结构层次序数、标点、段落序数:第一层为“一、”,第二层为“(一)”,第三层为“1”,第四层为“(1)”。不使用不规范的序号,如1)、
12、A、a等。标点:数字序号后统一用顿号,正文内容如果有需要编码序号时,须采用统一的手动序号编码,切勿一部分自动序号,一部分手动序号,造成排版格式的不一致。段落:每自然段文字开头前空2格,第2行起顶格。(5)数字数字除成文日期、部分结构层次序数和在词、词组、惯用语、缩略语、具有修辞色彩语句中作为词素的数字必须使用汉字外,应当使用阿拉伯数字。4、表格资料组统一提供的表格中已设定好的行宽、列高及文字不得任意修改。自制的表格要注意美观、居中,字体参考文档的要求。5、数据凡提供涉及统计数据的资料,必须准确无误,必须保持三年统计口径的一致性。二、落款、盖印所有纸质文字资料必须署上单位名称、日期,加盖公章。落
13、款位置在正文后空2行,单位名称按印章全称。盖印,可不写单位名称。成文日期中“”用插入符号里的几何图形,或用区位码0180,不能用阿拉伯数“0”。最后一个字离右边沿4格。盖章跨年月日,上2/3,下1/3,左右居中,端正清晰。三、照片 4R冲晒(或复印),一张A4纸放两张照片,每张照片需附文字说明,包括时间、地点、人物、事情。电子版的照片,每个活动设一个文件夹,同样要附文字说明。(不要将照片剪辑到Word上)四、复印上下左右居中对齐,如无特殊需要,版面图文的颜色均为黑色,尽量双页印刷,做到均匀清晰,杜绝漏印、倒印等错误现象。重要材料的复印件必须注明“与原件相符”字样,并加盖公章(红色)。五、装订一
14、律用夹子夹在左侧,不需装订。在首页的左上角用铅笔注明资料卷号,如:3-2-17六、注意事项学年和年度的区别,区划调整前后名称的区别,及时间的界定文档1. 保持文档整洁,书写工整,使用黑笔填写。2. 使用订数订装订文档左上角。3. 文档要分类摆放,site log和site folder分开。游戏软件文档编写规范 文档编写标准化:在游戏开发之先,实际上,美术,程序,游戏设计各部门及各部门之后,就已经有这个了,如游戏文件的命名,部门文档或文件的命名,还有一些文档或是表中,或是脚本中的说明书,都是此类 。 可行性分析报告:这个就是立项报告,游戏软件的可行性分析,一些要对比分析市场同类产品,风险评估等
15、等,在它个规范之外的东西。一般由主设计师及项目负责人来写一些与程序相关,与美术相关,也 峁喙氐氖 ?nbsp; 项目开发计划:这个面向的用户是团队及投资人,要非常清楚的写明各部门在各阶段计划完成什么。由项目负责人及各部门负责来写这个。 软件需求说明书:这个是由游戏设计部门与程序部门一起完成(但大部分公司游戏设计部门达不到这个水平),也就是游戏的数据结构啊,数据库列啊,等等东西 。 概要设计说明书:这个就是游戏的总案,用来指导团队开发的总方向,如果有变动,优先会改这个,就是一个游戏开发过程中的路灯,是由主设计师来写这个的。 详细设计说明书:这个在游戏开发过程中,由N个文档共同构成,但大概规范不必
16、拘泥,视写的文档的类型可自行调整。这是各部门都是如此,都有自己的规范。写这个,一般就是游戏设计师 用户操作手册:这个对应游戏开发,分两部分: 对内,在各目录中,各文档都应该有比较清楚的标释或是说明,作用在于如果新同事或是有人接你的工作,至少他应该可以知道怎么继续,程序部门对应的程序文件的注释。 对外,就是给玩家说明书,官方网站的一些内容,也在此例。 上面的工作,是由游戏设计部门完成(对内的,只对本部门) 测试计划:这个是由主设计师来做的,就是在内部内测时时,主要测什么,有多少人来做,如何测法,测试的目的要明确测试的目的,如同场景用户压力测试,门派平衡测试,模拟升级测试。 PS:题外一下,如果你
17、们的主程够强,一部分的测试可以虚拟机器完成,曾经的某项目中,在中期门派平衡测试和模拟升级测试,设计部门在没有软件的情况下,用excel都已经做的达到目的了 测试分析报告 :由各部门主管完成,要总结测试的结果,要修改的地方,如果修改等等,然后安排活大家分头去修改自己负责的地方 项目开发总结报告:这个,别的公司我不知道,但我每当一阶段都会自己做个总结的,如果是比较正规的公司会要求部门管理人员写这个的 软件维护手册:这个是交GM部门的,是由游戏设计部门来写的,对应网络游戏是这样的。包括GM的工具的设计,GM的培训计划等等 软件问题报告 :这个就是对应网络游戏软件,就是玩家反馈BUG或是一些意见的处理
18、行为的文档,由游戏设计部负责来完成,执行人为设计部与GM部门 软件修改报告:这个不是很需要报告的,但需要游戏设计部负责来安排这个工作,不管是哪的问题进行分流处理。2007年11月26日 星期一 10:53A、三种编写方法1、 用好的结构化和自然语言编写文本型文档;2、 建立图形化模型,这些模型可以描绘转换过程、系统状态、和它们之间的变化、数据关系、逻辑流或对象类和他们的关系;3、 编写形式化规格说明,这可以通过使用数学上精确的形式化逻辑语言来定义需求。多种编写方法可在同一个文档使用,根据需要选择,或互为补充,以能够把需求说明白为目的。B、应有成果1、 各业务手工办理流程文字说明;2、 各业务手
19、工办理流程图;3、 各业务手工办理各环节输入输出表单、数据来源;4、 目标软件系统功能划分(示意图及文字说明);5、 目标软件系统中各业务办理流程文字说明;6、 目标软件系统中各业务办理流程图(模型);7、 目标软件系统中各业务办理各环节数据、数据采集方式、数据间的内在联系分析。8、 目标软件系统用户界面图、各式系统逻辑模型图及说明C、文档工具推荐1、 调研结果需求分析说明书格式参照开发文档模板;2、 单位组织结构图、功能模块分解图用VISIO绘制,或直接用WORD中的画图工具;3、 业务流程图用VISIO中的FLOWCHART模板绘制;4、 系统逻辑模型使用ROSE绘制活用VISIO中的UM
20、L模板绘制;5、 软件用户界面用VISIO中的WIN95 USER INTERFACE模板绘制;6、 数据物理模型用POWERDESINER绘制;D、需求文档编写原则1、 句子简短完整,具有正确的语法、拼写和标点;2、 使用的术语与词汇表中所定义的一致;3、 需求陈述应该有一致的样式,例如“系统必须.”或者“用户必须.”,并紧跟一个行为动作和可观察的结果。;4、 避免使用模糊、主观的术语,减少不确定性,如“界面友好、操作方便”;5、 避免使用比较性词语,如“提高”,应定量说明提高程度软件工程文档编写标准在项目开发过程中,应该按要求编写好十三种文档,文档编制要求具有针对性、精确性、清晰性、完整性
21、、灵活性、可追溯性。 可行性分析报告:说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性,评述为了合理地达到开发目标可供选择的各种可能实施方案,说明并论证所选定实施方案的理由。 项目开发计划:为软件项目实施方案制订出具体计划,应该包括各部分工作的负责人员、开发的进度、开发经费的预算、所需的硬件及软件资源等。 软件需求说明书(软件规格说明书):对所开发软件的功能、性能、用户界面及运行环境等作出详细的说明。它是在用户与开发人员双方对软件需求取得共同理解并达成协议的条件下编写的,也是实施开发工作的基础。该说明书应给出数据逻辑和数据采集的各项要求,为生成和维护系统数据文件做好准备。 概要设计
22、说明书:该说明书是概要实际阶段的工作成果,它应说明功能分配、模块划分、程序的总体结构、输入输出以及接口设计、运行设计、数据结构设计和出错处理设计等,为详细设计提供基础。 详细设计说明书:着重描述每一模块是怎样实现的,包括实现算法、逻辑流程等。 用户操作手册:本手册详细描述软件的功能、性能和用户界面,使用户对如何使用该软件得到具体的了解,为操作人员提供该软件各种运行情况的有关知识,特别是操作方法的具体细节。 测试计划:为做好集成测试和验收测试,需为如何组织测试制订实施计划。计划应包括测试的内容、进度、条件、人员、测试用例的选取原则、测试结果允许的偏差范围等。 测试分析报告:测试工作完成以后,应提
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 项目 文档 编写 规范 代码
限制150内