如何写好设计文档

本文主要为需要编写软件设计/开发文档的读者提供一些经验和建议。阅读前提了解 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. 云厂商现状

    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 涉及与外部系统对接的文档当处理涉及到外部系统时，进行简要说明并附带外部系统的文档链接，如：观测云云关联处理逻辑

1. 查询所有当前系统内已有的主机列表
2. 调用 KODO API 获取本工作空间的 AK 列表
3. 根据主机列表调用云平台 API 获取 Meta 信息
4. 根据字段映射，更新方式写回主机对象【 KODO 获取 AK 列表接口文档 】https://gitlab.jiagouyun.com/...【 DataWay 更新对象数据 API 文档 】https://gitlab.jiagouyun.com/... 文档的管理和分发文档完成后，有条件的可以选择使用 git 管理，也可以使用普通网盘管理。当需要使用钉钉群发文档时，可以使用 Typora 的导出为 PDF 功能。方便没有 Markdown 编辑器的人直接在钉钉内预览方式阅读。