對于軟件工程師來說，文檔寫作是團隊合作和溝通的必備技能，特別是在遠程工作越來越流行的后疫情時代，文檔的重要性愈發重要。這篇文章分享了很多能夠幫助開發者提升文檔能力的資源，幫助我們寫出更好更容易維護的文檔。原文：Best Practices When Documenting Your Code for Software Engineers [1]

作為軟件工程師，掌握編寫高質量文檔的技能非常重要，特別是由于最近遠程工作的增加，在異步通信方面就需要做得更好。作為遠程工作的實踐者，GitLab在定義異步溝通 [2] 方面做得很好：

“異步溝通是一種溝通的藝術，無需在發送公開報告的同時讓所有相關方都到場，也可以推進項目向前。”

高質量的文檔是實現有效異步溝通的簡單方式。在這篇文章中，我將討論一些在個人經歷中非常有用的有趣的技巧。

谷歌技術寫作課程

谷歌為軟件工程師提供了免費的技術寫作課程。課程從技術寫作的基礎部分開始，分為兩個部分，內容如下：

谷歌技術寫作1

谷歌技術寫作2

沒人能夠在一夜之間就擅長技術寫作，這需要反復練習。我個人更喜歡每個月都去學習一下這門課程，以提醒自己什么才是寫作的最佳實踐。

使用Divio文檔框架

在所有文檔框架中，我個人最喜歡Divio [3] 。這里建議的文檔系統非常簡單并且普遍適用。

該框架建議將文檔分類如下：

• 教程（Tutorials）—— 面向學習的
• 指南（How-To Guides）—— 面向問題解決的
• 解釋（Explanation）—— 面向理解的
• 索引（Reference）—— 面向信息的

該方案被許多著名開源項目和企業廣泛采用 [4] 。

youtube上有一個很好的視頻，詳細解釋了框架的細節：https://youtu.be/t4vKPhjcMZg

使用基于markdown的文檔系統

在傳統企業中，可以使用各種方法來維護文檔。有些人喜歡創建MS Word/Excel文檔，然后上傳到SharePoint或OneDrives中。此類文檔最大問題是，無法使用內部搜索引擎進行搜索。因此，我個人更喜歡使用基于markdown的文檔系統。創建和維護這類文檔很容易，并且文檔是可搜索的。

如果你還不熟悉Markdown，可以查看GitHub上的免費課程 [5] ，輕松掌握這個工具。

使用Mermaid JS作圖

根據Mermaid [6] 的說法，這是“一個基于javascript的圖形和圖表工具，使用類似markdown的文本定義和渲染器來創建和修改復雜的圖表。”如果使用GitLab或Azure DevOps，原生就支持了Mermaid，如果使用GitHub或Atlassian的產品，那么可以通過插件使用。

使用Mermaid創建和更新圖表非常容易，不需要給每個開發人員安裝Visio/draw.io這樣的UML工具。

下面是一些用Mermaid創建的示例圖：

Mermaid序列圖示例

Mermaid類圖示例

可以立即嘗試使用Mermaid Live Editor [7] 創建圖表。

使用模板

像Confluence這樣的網站上有很多模板，可以用于特定類型的文檔。例如：

• 軟件架構評審模板（Software Architecture Review Template） [8]
• 架構決策記錄模板（Architecture Decision Record Template） [9]
• 事故分析模板（Incident Postmortem Template） [10]
• DevOps執行手冊（DevOps Runbook） [11]
• 決策模板（Decision Template） [12]
• 寫作指南（Writing Guidelines） [13]
• OKR模板（OKR Template） [14]
• 等等

參考風格指南（Style Guides）

如果你的團隊還沒有風格指南，可以參考一下谷歌和微軟的做法：

• Microsoft Style Guide [15]
• Google Developer Documentation Style Guide [16]

References: [1] Best Practices When Documenting Your Code for Software Engineers: https://betterprogramming.pub/best-practices-when-documenting-your-code-for-software-engineers-941f0897aa0 [2] How to embrace asynchronous communication for remote work: https://about.gitlab.com/company/culture/all-remote/asynchronous/ [3] Divio: https://www.divio.com/ [4] Who is using the system: https://documentation.divio.com/adoption/#adoption [5] Mastering Markdown: https://guides.github.com/features/mastering-markdown/ [6] Mermaid: http://mermaid-js.github.io/mermaid/ [7] Mermaid Live Editor: https://mermaid-js.github.io/mermaid-live-editor/ [8] Software Architecture Review Template: https://www.atlassian.com/software/confluence/templates/software-architecture-review [9] Lightweight Architecture Decision Records: https://github.com/deshpandetanmay/lightweight-architecture-decision-records/blob/master/doc/adr/0001-use-elasticsearch-for-search-api.md [10] Incident Postmortem: https://www.atlassian.com/software/confluence/templates/incident-postmortem [11] DevOps Runbook: https://www.atlassian.com/software/confluence/templates/devops-runbook [12] Decision Template: https://www.atlassian.com/software/confluence/templates/decision [13] Writing Guidelines: https://www.atlassian.com/software/confluence/templates/writing-guidelines [14] OKR Template: https://www.atlassian.com/software/confluence/templates/okrs [15] Microsoft Style Guide: https://docs.microsoft.com/en-us/style-guide/ [16] Google Developer Documentation Style Guide: https://developers.google.com/style

你好，我是俞凡，在Motorola做過研發，現在在Mavenir做技術工作，對通信、網絡、后端架構、云原生、DevOps、CICD、區塊鏈、AI等技術始終保持著濃厚的興趣，平時喜歡閱讀、思考，相信持續學習、終身成長，歡迎一起交流學習。