本文次要为须要编写软件设计 / 开发文档的读者提供一些教训和倡议。浏览前提理解 Markdown 语法理解 Typora、Sublime Text 或 VS Code 等不便编辑 Markdown 的编辑器面向读者须要编写产品 / 性能形容文档的产品经理、项目经理须要针对待开发性能编写根本设计、具体设计的软件工程师 1. 软件和文档格局抉择一般来说，软件开发相干的设计文档大多都具备以下特点：不须要特地花哨的款式常常须要批改除 UI 设计外，以纯文本为主根本构造、格局大体雷同常常有代码、数据呈现，须要不便复制因而，个别倡议此类文档应用纯文本的 Markdown 格局编写。Markdown 应用一些简略的标记语法，即可展示最罕用的题目、列表、重点、援用、代码块、链接等性能。前期也能不便地导出为 HTML、PDF 等格局。无关 Markdown 语法可参考：https://www.runoob.com/markdo… 设计文档的根本构造编写设计文档时，必须以「公司新人」的视角去编写，不能对读者实现所理解的内容做任何假如。因而，一份设计文档，一般来说至多须要蕴含以下几块内容：“一句话形容”的题目目录业务流程数据定义 2.1「一句话形容」的题目不要间接应用「文档」、「设计文档」作为文件名或题目。文件名或题目最好应用「一句话形容」，如：观测云新 Event 数据结构及解决逻辑设计观测云云关联解决逻辑设计这样，一来不容易有文件重名问题，二来读者可能在不关上文件的状况下，大抵理解文档内容。2.2 目录任何文档都要增加目录，这样能够不便读者在首次浏览时理解文档大抵内容，也能不便疾速查阅、跳转到特定内容。应用 Typora 能够抉择「段落 – 内容目录」插入目录应用 Sublime Text、VS Code 能够应用 MarkdownTOC 等插件生成目录留神：不同软件的目录实现形式不同，相互之间可能不兼容 2.3 业务流程任何设计文档都要对业务流程进行形容，具体写明「用户做了什么操作，零碎进行了什么解决，最初产生了什么」。对于简略的业务流程，能够间接应用列表进行形容，如：用户输出用户名、明码，点击登录零碎依据输出内容查找匹配的用户匹配胜利，跳转到 Dashboard 页面匹配失败，提醒「用户名或明码谬误」对于简单的业务流程，能够应用流程图形式形容，如：
提醒：流程图能够应用 ASCII Art、业余流程图工具、PowerPoint、Keynote 等软件进行绘制 2.4 数据定义业务流程中产生的业务实体，必须明确所有的字段、字段类型、取值范畴、数据起源等信息。假如存在业务实体「课程」，数据定义表格如下：
留神：表格中阐明不宜过长，对于某些须要简单阐明的字段，该当为其独自开设上级题目进行详细描述应用表格展现字段列表，构造更为清晰，对阅读者累赘也更低。此外，在因为在编写时也不容易脱漏字段的某些形容。对于 JSON 数据，也能够间接应用 JSON 格局展示，如：{
// [必须] 课程编号，全局惟一
"code": "CLASS-001",
// [必须] 课程名称
"name": "语文 1",
// [必须] 课程类型，可选值：理科 =`liberal`、文科 =`science`
"type": "liberal",
// [必须] 地位数量，取值范畴：`0 ~ 100`
"seatCount": 100,
// [必须] 课程创建人 ID。创立时主动填入
"userId": "user-001",
// [必须] 老师列表
"teachers": [
{// [必须] 老师的用户 ID
"userId": "user-002",
// [必须] 老师职位，可选值：主讲人 =`speaker`、助教 =`assistant`
"position": "speaker"
},
{
"userId": "user-003",
"position": "assistant"
}
],
// 课程标签，元素为 String
"tags": ["根底", "必修", "特级教师主讲"],
// 额定信息
"extraInfo": {
// 是否须要自带计算机
"computerRequired": false,
// 是否蕴含户外活动
"outdoorActivityIncluded": true
}}留神：应用 JSON 格局展示时，该当整顿为容易浏览的缩进格局举荐优先应用表格形式形容，JSON 形式次之，同时提供表格和 JSON 形式则为最佳！3. 更简单的设计文档对于小型零碎、单个功能模块的设计文档，提供上述 4 个根本内容根本能够满足需要。如果是针对整个零碎的形容，或者多个、简单功能模块的设计文档，那么就有必要减少更多的内容来进行阐明。3.1 拆分大型零碎的设计文档对于大型零碎的设计文档，该当将文档划分为层级：根本设计：形容零碎整体架构，但不必波及到具体性能外部的细节具体设计：形容具体功能模块、具体性能所波及的业务实体、解决流程、字段定义等 3.2 概念解释文档中呈现的的概念、业务实体须要明确的定义，防止误会。如：课程 class：指的是蕴含课件、教材的「课程内容」，如：「云计算入门」场次 activity：指的是某一个课程在特定工夫地点进行的流动，如：「云计算入门 2021 年上海第一场」并配合示例示例进行阐明。如：后盾管理员创立并录入「云计算入门」课程（这里操作的是「课程 class」）讲师依据排课表，抉择「云计算入门」开课，并指定开课时间（这里操作的是「场次 activity」）学生依据曾经开设的课程，抉择城市和工夫进行报名（这里操作的是「场次 activity」）优于疫情，勾销了 2020 年所有的培训（这里操作的是「场次 activity」）云计算曾经深入人心，没有持续开课的必要，「云计算入门」下架（这里操作的是「课程 class」）3.3 架构图无论是零碎整体设计，还是单个功能模块的设计，都能够附带架构图不便读者了解。如：DataFlux Func 的架构图
如：DataFlux Func 中「订阅器」的架构图
3.4 我的项目文件目录曾经成型的我的项目，一方面为了让新人可能疾速把握我的项目整体状况，另一方面为了标准后续开发工作，能够增加我的项目文件目录进行阐明。如：DataFlux Func 我的项目目录阐明
3.5 参考链接对于文档中呈现的关联、参考文档，该当列举进去，不便疾速参考。如：阿里云 ECS 列表 API 参考文档：https://help.aliyun.com/docum… 腾讯云 CVM 列表 API 参考文档：https://cloud.tencent.com/doc… EC2 列表 API 参考文档：https://boto3.amazonaws.com/v… 正当应用格局正当应用格局，能够帮忙读者更快地理解内容，升高浏览累赘。4.1 题目为每个题目加上分级编号，会使得目录更清晰，同时也能不便读者随时确定以后的浏览地位。如本文应用了 1.、1.1、1.1.1 形式编排大小标题但须要留神的是，题目层级不易过深，个别以不超过 4 层为佳。最小一层的题目能够思考不增加分级编号，如：1. 云计算概述
-
云厂商现状
2.1 国内 阿里云 腾讯云 华为云 2.2 国外 AWS Azure Oracle4.2 留神点、提醒点须要读者留神的中央，该当应用对立的强调格局，如：留神：所有的留神点都以「留神：XXX」格局出现同理，一些“顺便一提”的提醒内容，也该当应用对立的格局，如：提醒：所有的提醒都以「提醒：XXX」格局出现 4.3 列表列举内容时，该当应用列表形式展现，如：阿里云腾讯云 AWS 也能够附上简要阐明，如：阿里云：国内市场份额最大腾讯云：游戏行业用的比拟多 AWS：国外市场份额最大 4.4 链接附加官网、入口链接时，能够间接展现为能够点击的 URL 地址，如：https://docs.guance.com 如果所附带的链接为特定内容，数个链接列举，URL 地址很长等，该当为链接标注文字说明，如：【观测云产品介绍】https://docs.guance.com/getting-started/product-introduction/【观测云产品劣势】https://docs.guance.com/getting-started/product-introduction/advantages/5. 文档编写过程中的注意事项在文档编写过程中，对一些细节的把控，能够显著进步文档品质，缩小阅读者累赘。5.1 用词和形容的一致性前后一致的用词，不仅能够不便搜寻，也能进步浏览效率。正确示范：阿里云是国内份额最大的云厂商，绝大多数企业用户都抉择在阿里云上开展业务。与此同时，阿里云的产品也是国内云厂商中最为丰盛的一家。
姓名：字符串，必须，长度范畴 2～4
学校：字符串，必须，长度范畴 1～10
年龄：正整数，必须，取值范畴 1～99
身高：正整数，可选，取值范畴 1～200 谬误示范：aliyun 是国内份额最大的云厂商，绝大多数企业用户都抉择在阿里云上开展业务。
与此同时，Alibaba Cloud 的产品也是国内云平台中最为丰盛的一家。
姓名：字符串，必须，最短 2 个字符，最长 4 个字符
学校：必须，str，长度范畴 1～10
年龄：正整数，取值范畴 1～99，必须
身高：可选，大于 0 的整数，最大 2005.2 中英混排时的解决中英混排时，在英文前后增加空格会更容易浏览。[举荐] 英文前后有空格：阿里云的 ECS 是最外围的产品之一英文前后未有空格：阿里云的 ECS 是最外围的产品之一当中英混排的应为为字段名时，应用代码格局展现。[举荐] 字段名应用代码格局：接口返回的 InstanceId 字段是全局惟一的字段名未应用代码格局：接口返回的 InstanceId 字段是全局惟一的当波及按键时，应用按键格局展现[举荐] 应用按键格局：按 + 快捷键保留未应用按键格局：按 CTRL + S 快捷键保留 5.3 必要时附上代码示例有时，简明扼要不如一个残缺的示例更加直观，如：在 DataFlux Func 中编写如下代码，即可实现一个加法函数 @DFF.API(‘ 两数相加 ’)
def plus(x, y):
'''x, y 主动转换为浮点数'''
return float(x) + float(y)5.4 波及与内部零碎对接的文档当解决波及到内部零碎时，进行简要阐明并附带内部零碎的文档链接，如：观测云云关联解决逻辑
- 查问所有以后零碎内已有的主机列表
- 调用 KODO API 获取本工作空间的 AK 列表
- 依据主机列表调用云平台 API 获取 Meta 信息
- 依据字段映射，更新形式写回主机对象【KODO 获取 AK 列表接口文档】https://gitlab.jiagouyun.com/…【DataWay 更新对象数据 API 文档】https://gitlab.jiagouyun.com/… 文档的治理和散发文档实现后，有条件的能够抉择应用 git 治理，也能够应用一般网盘治理。当须要应用钉钉群发文档时，能够应用 Typora 的导出为 PDF 性能。不便没有 Markdown 编辑器的人间接在钉钉内预览形式浏览。