述

本文主要为需要编写软件设计/开发文档的读者提供一些经验和建议。

阅读前提

• 了解 Markdown 语法
• 了解 Typora、Sublime Text 或 VS Code 等方便编辑 Markdown 的编辑器

面向读者

• 需要编写产品/功能描述文档的产品经理、项目经理
• 需要针对待开发功能编写基本设计、详细设计的软件工程师

1. 软件和文档格式选择

一般来说，软件开发相关的设计文档大多都具有以下特点：

• 不需要特别花哨的样式
• 经常需要修改
• 除 UI 设计外，以纯文本为主
• 基本结构、格式大体相同
• 经常有代码、数据出现，需要方便复制

因此，一般建议此类文档使用纯文本的 Markdown 格式编写。

Markdown 使用一些简单的标记语法，即可展现最常用的标题、列表、重点、引用、代码块、链接等功能。后期也能方便地导出为 HTML、PDF 等格式。

有关 Markdown 语法可参考：https://www.runoob.com/markdown

2. 设计文档的基本结构

编写设计文档时，必须以「公司新人」的视角去编写，不能对读者实现所了解的内容做任何假设。

因此，一份设计文档，一般来说至少需要包含以下几块内容：

1. “一句话描述”的标题
2. 目录
3. 业务流程
4. 数据定义

2.1 「一句话描述」的标题

不要直接使用「文档」、「设计文档」作为文件名或标题。

文件名或标题最好使用「一句话描述」，如：

• 观测云新 Event 数据结构及处理逻辑设计
• 观测云云关联处理逻辑设计

这样，一来不容易有文件重名问题，二来读者能够在不打开文件的情况下，大致了解文档内容。

2.2 目录

任何文档都要添加目录，这样可以方便读者在首次阅读时了解文档大致内容，也能方便快速查阅、跳转到特定内容。

使用 Typora 可以选择「段落 - 内容目录」插入目录

使用 Sublime Text、VS Code 可以使用 MarkdownTOC 等插件生成目录

注意：不同软件的目录实现方式不同，互相之间可能不兼容

2.3 业务流程

任何设计文档都要对业务流程进行描述，具体写明「用户做了什么操作，系统进行了什么处理，最后发生了什么」。

对于简单的业务流程，可以直接使用列表进行描述，如：

1. 用户输入用户名、密码，点击登录
2. 系统根据输入内容查找匹配的用户
3. 匹配成功，跳转到 Dashboard 页面
4. 匹配失败，提示「用户名或密码错误」

对于复杂的业务流程，可以使用流程图方式描述，如：

提示：流程图可以使用 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 拆分大型系统的设计文档

对于大型系统的设计文档，应当将文档划分为层级：

1. 基本设计：描述系统整体架构，但不用涉及到具体功能内部的细节
2. 详细设计：描述具体功能模块、具体功能所涉及的业务实体、处理流程、字段定义等

3.2 概念解释

文档中出现的的概念、业务实体需要明确的定义，避免误解。如：

• 课程class：指的是包含课件、教材的「课程内容」，如：「云计算入门」
• 场次activity：指的是某一个课程在特定时间地点进行的活动，如：「云计算入门 2021 年上海第一场」

并配合示例示例进行说明。如：

1. 后台管理员创建并录入「云计算入门」课程（这里操作的是「课程class」）
2. 讲师根据排课表，选择「云计算入门」开课，并指定开课时间（这里操作的是「场次activity」）
3. 学生根据已经开设的课程，选择城市和时间进行报名（这里操作的是「场次activity」）
4. 优于疫情，取消了 2020 年所有的培训（这里操作的是「场次activity」）
5. 云计算已经深入人心，没有继续开课的必要，「云计算入门」下架（这里操作的是「课程class」）

3.3 架构图

无论是系统整体设计，还是单个功能模块的设计，都可以附带架构图方便读者理解。

如：DataFlux Func 的架构图

如：DataFlux Func 中「订阅器」的架构图

3.4 项目文件目录

已经成型的项目，一方面为了让新人能够快速掌握项目整体情况，另一方面为了规范后续开发工作，可以添加项目文件目录进行说明。如：DataFlux Func 项目目录说明

3.5 参考链接

对于文档中出现的关联、参考文档，应当罗列出来，方便快速参考。如：

• 阿里云 ECS 列表 API 参考文档：https://help.aliyun.com/document_detail/25506.html

• 腾讯云 CVM 列表 API 参考文档：https://cloud.tencent.com/document/product/213/15728

• AWS EC2 列表 API 参考文档：https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html

4. 合理使用格式

合理使用格式，可以帮助读者更快地理解内容，降低阅读负担。

4.1 标题

为每个标题加上分级编号，会使得目录更清晰，同时也能方便读者随时确定当前的阅读位置。如本文使用了1.、1.1、1.1.1方式编排大小标题

但需要注意的是，标题层级不易过深，一般以不超过 4 层为佳。最小一层的标题可以考虑不添加分级编号，如：

1. 云计算概述
2. 云厂商现状
        2.1 国内
                阿里云
                腾讯云
                华为云
        2.2 国外
                AWS
                Azure
                Oracle

4.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 的整数，最大 200

5.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 列表
2. 根据主机列表调用云平台 API 获取 Meta 信息
3. 根据字段映射，更新方式写回主机对象

【 KODO 获取 AK 列表接口文档 】https://gitlab.jiagouyun.com/cloudcare-tools/kodo/-/blob/dev/apis.md#v1keyconfigget-get

【 DataWay 更新对象数据 API 文档 】https://gitlab.jiagouyun.com/cloudcare-tools/kodo/-/blob/dev/apis.md#v1keyconfigget-get

6. 文档的管理和分发

文档完成后，有条件的可以选择使用 git 管理，也可以使用普通网盘管理。

当需要使用钉钉群发文档时，可以使用 Typora 的导出为 PDF 功能。方便没有 Markdown 编辑器的人直接在钉钉内预览方式阅读。

文 | 汤佩兰

责编 | 陈晓雪

2020年10月5日，2020年诺贝尔生理学或医学奖颁发给了三位发现丙肝病毒（HCV）的病毒学家，分别是哈维·奥尔特（Harvey James Alter），迈克尔·霍顿（Michael Houghton）和查尔斯·莱斯（Charles M. Rice）。这让丙肝病毒的发现和治疗再次进入媒体和大众的视野。

“虽然诺奖（颁给丙肝病毒工作）我很高兴，但是丙肝这一块，我觉得还不是最好的状态，”10月5日晚，盖茨基金会北京办事处副主任徐福洁对《知识分子》表示。

2016年，世界卫生组织（WHO）提出2030年消除病毒性肝炎作为重大公共卫生威胁的总体目标。肝炎病毒是全球肝炎的最常见病因,其中乙型和丙型肝炎导致数亿人罹患慢性疾病，二者还是肝硬化和癌症的最常见病因。

今年6月，《健康中国2030消除丙肝威胁行动白皮书》（下简称《白皮书》）发布，提到中国估计有超过760万例慢性丙肝患者。他们若不能得到及时治疗，15-30%的患者会在30年内发展出肝硬化、肝衰竭甚至肝癌等一系列健康问题。《白皮书》指出，我国对消除丙肝公共卫生威胁缺少国家层面更细致的统一规划和目标;另外就是在丙肝防治的各个环节，大众对于丙肝的认识不足，导致从预防、筛查到诊疗等各个环节都有问题产生[1]。

根据2019年一项综合统计数据，丙肝在中国诊断率仅为22.51%，治疗率仅为3.49%[2]。上述《白皮书》提到，丙肝在早期感染阶段几乎没有明显症状，会无意间加剧病毒的蔓延，因此在感染早期阶段通过筛查将患病人群筛查出来进行感染阻断，对全面消除丙肝的目标具有决定性作用。

徐福洁曾在美国联邦疾病控制中心（CDC）工作，从事肝炎相关工作十多年，在2015年到2017年间还作为吉利德亚太地区项目负责人（medical director），专门为该地区中低收入国家丙肝病人能够用上低价丙肝药开展了一系列工作。

徐福洁表示，对于丙肝的防治，我们还没有真正把这件事情做清楚，“需要利用好现在的这些检测、治疗的手段。尽管相对于其他很多疾病，丙肝在国内不是特别严重，但是未来因为丙肝得肝癌或者得肝硬化，是不该再发生的事了。”

对于三位获奖人，徐福洁都有过一起开会的经历，在美国工作的时候，跟奥尔特一同参加了庆祝丙肝病毒发现20周年的活动。印象最深刻的是与奥尔特相处的经历，

“Alter这个人特别幽默，他回忆自己的发现，开玩笑说自己没什么创造性，不是creative person，所以当他知道不是甲肝，也不是乙肝的时候，就命名一个非甲非乙肝炎（non-A,non-B hepatitis）。”

20世纪70年代，奥尔特与其研究小组证明，大多数输血后肝炎病例不是由甲型和乙型肝炎引起的，因此将其命名为“非甲非乙肝炎”。通过对黑猩猩的传播研究表明，进一步发现这种新型肝炎引起的感染是一种新型病毒。

那么，当年奥尔特博士为什么会关注肝炎的问题呢？

徐福洁介绍，奥尔特并非直奔丙肝病毒的研究，最初就是为了保证血液安全这一临床问题。“奥尔特博士是NIH（美国国立卫生院）血液安全小组的，他做的工作相对来说不是基础研究，而是保证输血安全，因为输血后有肝炎发生。当时他就开始着手怎么降低这个事。”

当时已有研究表明多次输血患者中有30%的肝炎发病率，主要跟使用商业血库有关。到1970年，NIH血库转为志愿者血库之后肝炎发病率下降到约10%，但其中乙肝仅占全部肝炎的30%。等到1975年，科学家们通过检测和推理发现一部分病例不是甲肝也不是乙肝，由于当时尚未证明这是一种新的病毒，因此一开始没有使用丙型肝炎，而是采用了不确定性更强的术语进行命名[3]。

徐福洁感慨地说，从2000年开始就有人预测丙肝病毒的工作可能得诺奖，到现在20年了，今天获奖，很可能有新冠疫情的促进作用。“要不然都是肿瘤方面的。今年我觉得是回到一个普通的病毒。”

她同时表示，诺奖委员会肯定了发现丙肝病毒的工作，诺奖得主们的工作当然是有很多“惊喜”，但还有其他人做了大量相关工作，“这真是一个很宏大的过程”。

徐福洁所说的相关工作，就包括2013年在美国上市的第一个抗丙肝病毒的核苷类聚合酶抑制剂索非布韦（Sofosbuvir）发明者迈克尔·索非亚（Michael J. Sofia）。

由于索非布韦的发明让丙肝患者从几乎无药可治到绝大多数患者能够更快、副作用更少的被治愈，索非亚凭借该发明获得了2016年的拉斯克医学奖。

“看到（诺奖的）消息，这些人都还挺年轻的。在这次看来觉得诺奖真的没那么神秘，就是那么多人做的工作。”徐福洁说道。

参考链接：

[1]《健康中国2030消除丙肝威胁行动白皮书》发布

http://liver.org.cn/portal.php?mod=view&aid=776

[2] https://cdafound.org/dashboard/polaris/dashboard.html

[3] Harvey J. Alter, The road not taken or how I learned to love the liver: A personal perspective on hepatitis history, Hepatology

https://aasldpubs.onlinelibrary.wiley.com/doi/full/10.1002/hep.26787

色字体有链接 链接在旁边

Node-RED系列文章目前已经写了9篇，介绍了Node-RED的安装以及默认安装的一些基本节点的使用，作为物联网的一个可视化拖动的流程,Node-RED的确实很容易上手。还没开始学习的同学可以先看下我以前的文章

• 物联网平台Node-RED系列（一）：Node-RED的介绍与安装
• 物联网平台Node-RED系列（二）：Node-RED的面板的操作
• 物联网平台Node-RED系列（三）：Node-RED公共节点的使用
• 物联网平台Node-RED系列（四）：Node-RED函数节点的使用
• 物联网平台Node-RED系列（五）：Node-RED序列节点的使用
• 物联网平台Node-RED系列（六）：Node-RED解析节点的使用
• 物联网平台Node-RED系列（七）：Node-RED存储节点的使用
• 物联网平台Node-RED系列（八）：Node-RED网络节点的使用
• Node-RED系列（九）：Node-RED面板dashboard节点的使用

上一期我给大家介绍了dashboard的安装以及一个按钮的配置，这一期我们来更加系统地学习一下dashboard的节点配置。

上一期我们已经知道 dashboard的库一共有16个节点，分别是

• button 按钮节点
• dropdown 下拉选择节点
• switch 开关节点
• slider 轮播图
• numeric 数字滑块
• text input 文本输入
• date picker 日期选择
• colour picker 颜色选择器
• form 表单
• text 文本显示
• gauge 仪表板
• chart 图表，折线图
• audio out 音频输出
• notification 通知
• ui control ui控制
• template 模板

本篇文章我就给大家多讲解几个节点的使用与配置。

首先我们要了解dashboard这个库,
库的介绍，https://flows.nodered.org/node/node-red-dashboard
库的github源码 https://github.com/node-red/node-red-dashboard
目前899个star，还是挺不错的。
dashboard的布局可以看做是一个网格布局，每一个group（组），都有一个默认的宽度，6个单位（每个单位48px，并且6px的间隔）
每一个部件都必须存在于一个group中，这里的部件其实就是指一个UI元素，像按钮，输入框，选择框，数字滑块。每一个部件的宽度默认是auto.这意味着它将布满整个group，并且会自适应单位。

给定一个宽度为6的组，如果你添加六个小部件，每个小部件的宽度为2，则它们将分两行布置-每行三个小部件。

如果你添加两组宽度6，只要你的浏览器窗口足够宽，它们就会并排放置。如果缩小浏览器，则某一列中的第二组有时会移到第一组之下。

建议尽可能使用多个组，而不是一个大组，以便页面可以在较小的屏幕上动态调整大小。

在布局中，最大的布局单位是tab，以下是group，然后是部件 widget
你可以在右上角点击 一个柱形图的图表来查看dashboard的操作面板

site配置

主题色配置

可以对主题进行自定义

Style选中Custom，就可以选择自定义的颜色。

关于图标，dashboard内置了四套图标。
分别是

• Angular Material icons : angular图标 如send
• Font Awesome 4.7 : 字体图标 如fa-fire fa-2x
• Weather Icons Lite : 天气图标 如wi-wu-sunny
• Material Design Iconfont ; Material设计图标 如mi-alarm_on

如图配置了所有的UI组件到流中，

UI组件只要不涉及到数据的流转，那就可以不用连线，依然可以显示到页面上。
上面的流配置 显示的页面是这样子的

由于group的默认是6个单位，所以会有点小。我们可以点击这里进行调整宽度

调整后的效果图

没有那么小了，会稍微好看很多。

最后再给大家看一下dashboard支持的图标库吧。

angular-material-icons https://klarsys.github.io/angular-material-icons/

Font Awesome 4.7 https://fontawesome.com/v4.7.0/icons/

Weather Icons Lite https://github.com/Paul-Reed/weather-icons-lite/blob/master/css_mappings.md

[Material Design Iconfont](https://jossef.github.io/material-design-icons-iconfont/)