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

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

“異步溝通是一種溝通的藝術(shù)，無需在發(fā)送公開報(bào)告的同時(shí)讓所有相關(guān)方都到場(chǎng)，也可以推進(jìn)項(xiàng)目向前?！?/p>

高質(zhì)量的文檔是實(shí)現(xiàn)有效異步溝通的簡(jiǎn)單方式。在這篇文章中，我將討論一些在個(gè)人經(jīng)歷中非常有用的有趣的技巧。

谷歌技術(shù)寫作課程

谷歌為軟件工程師提供了免費(fèi)的技術(shù)寫作課程。課程從技術(shù)寫作的基礎(chǔ)部分開始，分為兩個(gè)部分，內(nèi)容如下：

谷歌技術(shù)寫作1

谷歌技術(shù)寫作2

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

使用Divio文檔框架

在所有文檔框架中，我個(gè)人最喜歡Divio [3] 。這里建議的文檔系統(tǒng)非常簡(jiǎn)單并且普遍適用。

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

• 教程（Tutorials）—— 面向?qū)W習(xí)的
• 指南（How-To Guides）—— 面向問題解決的
• 解釋（Explanation）—— 面向理解的
• 索引（Reference）—— 面向信息的

該方案被許多著名開源項(xiàng)目和企業(yè)廣泛采用 [4] 。

youtube上有一個(gè)很好的視頻，詳細(xì)解釋了框架的細(xì)節(jié)：https://youtu.be/t4vKPhjcMZg

使用基于markdown的文檔系統(tǒng)

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

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

使用Mermaid JS作圖

根據(jù)Mermaid [6] 的說法，這是“一個(gè)基于javascript的圖形和圖表工具，使用類似markdown的文本定義和渲染器來創(chuàng)建和修改復(fù)雜的圖表?！比绻褂肎itLab或Azure DevOps，原生就支持了Mermaid，如果使用GitHub或Atlassian的產(chǎn)品，那么可以通過插件使用。

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

下面是一些用Mermaid創(chuàng)建的示例圖：

Mermaid序列圖示例

Mermaid類圖示例

可以立即嘗試使用Mermaid Live Editor [7] 創(chuàng)建圖表。

使用模板

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

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

參考風(fēng)格指南（Style Guides）

如果你的團(tuán)隊(duì)還沒有風(fēng)格指南，可以參考一下谷歌和微軟的做法：

• 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做過研發(fā)，現(xiàn)在在Mavenir做技術(shù)工作，對(duì)通信、網(wǎng)絡(luò)、后端架構(gòu)、云原生、DevOps、CICD、區(qū)塊鏈、AI等技術(shù)始終保持著濃厚的興趣，平時(shí)喜歡閱讀、思考，相信持續(xù)學(xué)習(xí)、終身成長，歡迎一起交流學(xué)習(xí)。