述

本文主要為需要編寫軟件設計/開發文檔的讀者提供一些經驗和建議。

閱讀前提

• 了解 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/)