B2 《设计书执笔要领》
1.目的
本《设计书执笔要领》是某某系统（以下简称“本系统”）开发中按照设计书的最终版本编排的标准规范要求，目的是对表、图、正文、附录等都用统一的表现形式来制作均质的设计书，以提高设计书的形式品质。
2.如何书写优质设计书
（1）什么是好的文档
好的文档要用与读者水平相当的记述手法来记述，以让读者较清晰容易地把握文档内容。
另外，技术文档不是文学作品，不需要有文采地描述，只需要简洁明了，详细具体地正确说明问题即可。
（2）执笔者的思想准备
做出高品质的文档，需要一定的表述技能，更需要作者倾注一番心血，因此编写时要注意以下几点。
①正确地记述内容。
②明朗简洁的方式。
③图表的适当使用。
④语法与标点符号的统一。
3.执笔要领
（1）5W1H手法
文档内容记述时要切实遵循5W1H的手法。在有多个项目说明的场合，如果只用文字来说明，那么可能会产生歧义；另外，对于多项内容或者条件等复杂关系进行表述时，如果不用矩阵表或者判定表等记述手法来表现的话，很难说明白。因此，5W1H手法是软件开发中很重要的技能之一。5W1H手法如附表B2-1所示。
附表B2-1 5W1H手法
（2）一般注意事项
①要避免用推测的表达手法。
推测的表现语句会给读者造成不安，这样就会失去对文档的信赖，所以执笔者一定要怀有信心，用肯定的语句进行表述。
是否有推测的表述，从用词就可判断，例如：“希望”“大概”“基本的”“原则”等词就要避免使用。
②要避开抽象的表达手法。
如果用抽象的语言来表述的话，就不会让读者明白具体的目标，因此就不能满足客户的期待。
抽象的表现一般有以下两种情况。
a.用“极力”“尽可能”“等等”“高效率的”等方面的副词。
b.用给人模糊概念的形容词，例如：“～的”“～性”“～化”，这种定性化的表达手法也是要避免的。
③对于事实要用具体的定量形式记述。
a.表示强调的副词不要使用。
表示强调的副词一般有“非常的”“全体”等，这些要避免。
b.不要乱用代词。
代词往往会引起误解，因此只有在不能引起误解的地方使用代词。
c.不要用夸张描述。
如果对事实进行夸赞的话，往往也会产生误解。在用简单且容易理解的形式进行内容记述时，系统不能实现的限制亦要进行具体的说明。
d.尽量用数字、图表来表现。
不要有太长的描述，要简单明了，且不要产生误解。此时要注意以下两点：
不要把图表内容做错了。如果把数值或者图表做错了，就会引起很大的麻烦。
不要乱用图表。过度使用图表也会显得内容没有主次，因此如何在适当的地方使用就凸显出执笔者的写作水平。
e.要避免长文。
一句话，只需说明一个问题即可。如果一句话说明两件以上的事情，就会产生不当的长文。一般来说，一句话控制在50字以内，最多100字。
f.按条目写。
如果要写的内容有好多页，可以把主要的项目分别按照条目进行书写，因此读者（客户或者评审者等）就可以很好地理解设计意图。
g.要给出适合的例子。
在进行一般性的论述时，要给出适合的例子。例子可以是文字以外的图、表、图片、插图、示例等，这些例子可以给读者最直观的感受，这样会大大提高文档的内容品质。
h.标准化。
按照设计书规约来做，这样图表的标号、版式等就会比较标准。
i.系统共通设计要进行具体记述。
在对信赖性、安全性、扩展性、运用性、经济性等进行记述的时候，要有具体的记述内容。另外，各种特性如果有实施条件的话，亦不要漏掉。
例如：如果只是“～可以提高安全性与经济性”的这种记述的话，客户可能就会产生“可以得到安全性高，经济性好的产品”的误解。此时，一种正确的做法是“～采用加密计算进行加密以提高安全性，同时对数据交换采用压缩技术以降低流量，提高效率与经济性”，以这样具体的方式进行记述，就比较客观明了。
④其他。
a.主语与宾语要明确。
b.不要过度省略。
c.不要使用二重否定。
d.有条件的场合，要明确记明“是”与“否”。
4.执笔基准
（1）编号体系
①标题。
各设计书的标题部分要分别作为一页来设计，在本页里面要有版本数与改版日。另外，下一页要有改版记录，再下一页是目录。
②别册标题。
有些项目可能有补足用的别册，别册的标题和正文是一样的。
③章编号、节编号及项目编号。
其编号用阿拉伯数字与英文句号来表示，最大3位。另外，对于新的一章来说一定要改页。
1XXXX……………章编号
1.1XXXX……………节编号
1.1.1XXXX……………节编号项目编号
④细别符号。
章节项目编号最大3阶层，那么更详细的分类信息可以用如附表B2-2所示的细别符号。
附表B2-2 细别符号
⑤图表编号。
图编号、表编号、附图编号及附表编号要分别独立地赋予。另外，多个图表的情况，要在题名的后面用分隔符表示。
a.图编号。
图编号，如下所示。
图“章编号”-“章内连号”
b.表编号。
表编号，如下所示。
表“章编号”-“章内连号”
c.附图编号。
附图编号，就是附录里面的图的编号，如下所示。
附图“附录内章编号”-“章内连号”
d.附表编号。
附表编号，就是附录里面的表的编号，如下所示。
附表“附录内章编号”-“章内连号”
⑥脚注编号。
脚注编号要放在文句的右上肩，而且是在页内连号，如下所示。
365IT学院①架构师的摇篮
⑦页编号。
正文与附录的页编号要独立赋予。
a.文本与附录。
文本与附录页编号，如下所示。
“章编号”-“章内连号”
b.编或者章标题。
编或者章标题，不赋予编号。
c.改版记录与目录。
需要与正文及附录的页码要独立出来，如下所示。
（“连号”）
（2）用字与用语
关于技术类文档的执笔基准所使用的用字与用语。
①汉字。
使用常用汉字，固有名词除外（地点、人名等）。
②数字。
使用阿拉伯数字与罗马数字（Ⅰ、Ⅱ、Ⅲ等）。
③英文。
英文用美国标准26个半角字母（大小写）。
④省略语。
这里的省略语一般指的是英文省略语。省略语要大写，而且要在最初出现的地方对组成省略语的单词进行解释（在括号内单词用全称）。如：UT（UnitTest）。
（3）记号
关于技术类文档的执笔基准所使用的记号。
①中文句号“。”。
一句话结束时使用。
②英文句号“.”。
以下3处需要使用。
a.英文省略号。
b.章节编号。
c.小数点。
③中文逗号“，”。
在文章里叙述文字，需要用逗号时，使用中文逗号。
④英文逗号“，”。
在数字里面，根据格式需求，要用英文逗号。
⑤顿号“、”。
一句话中，需要进行明确区分词之间时使用。但是不要随便乱用（因为顿号位置变动会引起歧义，或者变得难以理解）。正确的使用如下所示。
a.用于分隔句中的并列词语。
b.为了降低一句话的难度，在必要位置加上顿号。
⑥中点“·”。
在以下的场合时需要使用：
a.关联的名词组合在一起作为一个词。
b.作为条目记号。
⑦冒号“：”。
在以下的场合时需要使用。
a.列举事例之后。
b.单词说明。
c.表示比例或者时刻。
⑧连字短横线“-”。
在以下场合时需要使用。
a.图表编号或者页码编号。
b.管理编号等体系里（如文件编号）。
⑨斜线“/”。
在以下场合时需要使用。
a.数学领域的分数或除法（1/2）。
b.日期表示形式（2017/1/17）。
c.单位记号中（t/s）。
⑩波浪线“～”。
在时间、场所、顺序的起始点之后及终点之前使用。
（11）中文双引号““””。
在以下场合时需要使用。
a.强调。
b.引用别的话语。
（12）括号。
a.大括号“{}”。
小括号的外面需要再加括号时使用，属于小括号的高位括号。
b.中括号“[]”。
方法的参数或者章节引用时使用。
c.小括号“（）”。
文中需要增加说明或者注释的地方。
d.尖括号“＜＞”。
小括号内需要再加括号时使用，属于小括号的低位括号。
e.上下括号“「」”。
引起注意等强调时使用。
f.方头括号“【】”。
引起注意等强调时使用。
g.六角括号“〔〕”。
脚注或操作说明书中可省略输入项目时使用。
除上述的各种符号以外，其他符号都不应该使用，如以下符号：
省略号“……”、英文单引号“’”、英文双引号“＂”等。
（4）记述
①文体。
体裁以说明文的形式进行记述。
②引用。
有著作权的引用与没有著作权的引用的记载方式是不一样的，这点要引起注意。
a.没有著作权网络资料的引用记载方式。
引用要尽可能地控制在必要最低限度范围，并记载出处。
引用的内容不要擅自修改。
b.有著作权内容的引用记载方式，如附表B2-3所示。
附表B2-3 著作权引用记载方式
③强调。
强调语句等要进行强调的时候，在需要强调的文字上加下画线。
④表标题行背景色。
推荐使用15%的灰色来表示。
⑤参照。
a.同一文档内。
正文或者附录。
正文或附录里面的引用，需要把引用的该章的章编号、节编号、项编号及细节符号在中括号里进行引用说明，并做引用连接，位置可以放在句子的中间或末尾。注意不需要记述标题，如下所示。
………[参照1-2（1）]…。
………。[参照附录1-1]
图或表。
其参照与正文或附录一样。另外，如果是同一页内的图或者表，可以用“上图”“下图”“左图”“右图”等表示方位的词来表示。
b.其他文档，如下所示。
………[参照图1-2（1）]…。
………。[参照表1-1]
………。[参照上图]
该段的末尾参照的文档的名称用[]来表示。注意不需要写文档的地址，因为文档可能会随时移动，如下所示。
………。[参照登录设计书.doc]
⑥脚注。
a.在正文或者图中的特定的语句及词进行必要的脚注时，在其右肩赋予脚注编号，并且要关联到脚注文。
脚注文的位置要注意以下几点。
文字脚注，要放在本段的最后。
图表脚注，要放在图表的下面。
（5）图表
图表可以给读者直观的视觉效果，对于读者来说，可以大大降低其理解文档的难度。特别是软件行业，概念性与抽象性的说明在前期很多，配合图表可以把复杂事情简单化，能较容易地把正确信息传递给读者。
①共通事项。
a.图表的标题必须有。
b.图表的标题必须能正确表达图表的内容。
c.图表必须放在正文内容合适的位置。
d.图表要尽可能地放到同一页里面，如果需要分页来放，需要按如下所示进行说明。
图1-2“题名”（“同一图表编号内连号“/”同一图表编号内最大编号）”
e.如果正文最后放图表的空白不是很充足，那么空白就可以保留，要改页来放。
f.图表的字体不要太小，避免打印出来看不清。
g.图的中心要和纸的中心吻合。
h.名称要在编号的后面，且留一个空格。
②不同事项。
a.图的编号与名称要在图的下方，中间排列。
b.表的编号与名称要在表的上方，中间排列。
5.文档制作基准
（1）使用的软件
软件使用明细如附表B2-4所示。
附表B2-4 软件使用明细
（2）格式
①纸大小及空白。
设计书文本的大小要用A4，印刷方向是纵向排版。
大的图、表、数据库ER图、功能处理流程图、页面转移图等要用A3且横向排版。如果要在设计书正文里插入A3页面的话，那么为了最后装订及更容易地看到次页信息，要进行两次折叠处理。
另外，对于流程图、页面转移图等A3纸没有特殊要求，一般是进行别册打印的。
注意：印刷的方向，以读者易读的统一的方向进行，这样可以使得读者更能集中注意力进行阅读。横纵混合编排是非常不好的编排形式，在必要情况下，A4纸张作为别册进行横向印刷也是可以的。
a.空白以及页眉与页脚。
页眉/页脚边距如附表B2-5所示。
附表B2-5 页眉/页脚边距
b.文字数与行数。
不要超过打印线。
注意：对于Excel文件，编写设计书时，由于反复增删内容，往往很容易出现超出打印线的情况。有一个小技巧，那就是打印之前或者完成后先预览一下，看看效果再打印。
②装订注意事项。
a.打孔装订。
设计书非常厚时（即订书机不能装订，一般在50页以上），需要进行打孔装订。打孔个数为两个，位置要统一。
b.订书机装订。
装订位置在左上角，钉子两脚位置与纸边距离为7mm，且钉子与纸的两边成正三角形。一次用力装订好，以保证装订的品质与美观。
③文件的属性设置。
a.文件概要属性。
标题。用文件标题来记述。
作者。姓名全称，例如：颜廷吉。
公司名称。作者所属公司全称，例如：上海颐凡软件科技有限责任公司。
客户设定。
b.版数。
版数格式为“第X.X.X版”。
c.系统名称。
记入开发的系统全名。
d.文档编号。
根据文档编号体系，记入文档的编号信息。
④使用字体。
a.正文。
正文使用“宋体”“小五号”标准大小。
b.各标题。
标题要有层次感，最多3层，使用“标题宋体”，大小分别为“小四”“五号”“小五号”。