建站
咨詢
售后
建站咨詢
新聞中心
作為軟件工程師，掌握編寫高質量文檔的技能非常重要，特別是由于最近遠程工作的增加，在異步通信方面就需要做得更好。作為遠程工作的實踐者，GitLab在定義異步溝通 [2] 方面做得很好：
站在用戶的角度思考問題，與客戶深入溝通，找到鎮(zhèn)安網(wǎng)站設計與鎮(zhèn)安網(wǎng)站推廣的解決方案，憑借多年的經(jīng)驗，讓設計與互聯(lián)網(wǎng)技術結合，創(chuàng)造個性化、用戶體驗好的作品，建站類型包括：成都網(wǎng)站建設、網(wǎng)站設計、企業(yè)官網(wǎng)、英文網(wǎng)站、手機端網(wǎng)站、網(wǎng)站推廣、國際域名空間、虛擬空間、企業(yè)郵箱。業(yè)務覆蓋鎮(zhèn)安地區(qū)。
“異步溝通是一種溝通的藝術，無需在發(fā)送公開報告的同時讓所有相關方都到場，也可以推進項目向前?！?/p>
高質量的文檔是實現(xiàn)有效異步溝通的簡單方式。在這篇文章中，我將討論一些在個人經(jīng)歷中非常有用的有趣的技巧。
谷歌技術寫作課程
谷歌為軟件工程師提供了免費的技術寫作課程。課程從技術寫作的基礎部分開始，分為兩個部分，內容如下：
谷歌技術寫作1
谷歌技術寫作2
沒人能夠在一夜之間就擅長技術寫作，這需要反復練習。我個人更喜歡每個月都去學習一下這門課程，以提醒自己什么才是寫作的最佳實踐。
使用Divio文檔框架
在所有文檔框架中，我個人最喜歡Divio [3] 。這里建議的文檔系統(tǒng)非常簡單并且普遍適用。
該框架建議將文檔分類如下：
- 教程（Tutorials）—— 面向學習的
- 指南（How-To Guides）—— 面向問題解決的
- 解釋（Explanation）—— 面向理解的
- 索引（Reference）—— 面向信息的
該方案被許多著名開源項目和企業(yè)廣泛采用 [4] 。
youtube上有一個很好的視頻，詳細解釋了框架的細節(jié)：https://youtu.be/t4vKPhjcMZg
使用基于markdown的文檔系統(tǒng)
在傳統(tǒng)企業(yè)中，可以使用各種方法來維護文檔。有些人喜歡創(chuàng)建MS Word/Excel文檔，然后上傳到SharePoint或OneDrives中。此類文檔最大問題是，無法使用內部搜索引擎進行搜索。因此，我個人更喜歡使用基于markdown的文檔系統(tǒng)。創(chuàng)建和維護這類文檔很容易，并且文檔是可搜索的。
如果你還不熟悉Markdown，可以查看GitHub上的免費課程 [5] ，輕松掌握這個工具。
使用Mermaid JS作圖
根據(jù)Mermaid [6] 的說法，這是“一個基于javascript的圖形和圖表工具，使用類似markdown的文本定義和渲染器來創(chuàng)建和修改復雜的圖表?！比绻褂肎itLab或Azure DevOps，原生就支持了Mermaid，如果使用GitHub或Atlassian的產(chǎn)品，那么可以通過插件使用。
使用Mermaid創(chuàng)建和更新圖表非常容易，不需要給每個開發(fā)人員安裝Visio/draw.io這樣的UML工具。
下面是一些用Mermaid創(chuàng)建的示例圖：
Mermaid序列圖示例
Mermaid類圖示例
可以立即嘗試使用Mermaid Live Editor [7] 創(chuàng)建圖表。
使用模板
像Confluence這樣的網(wǎng)站上有很多模板，可以用于特定類型的文檔。例如：
- 軟件架構評審模板（Software Architecture Review Template） [8]
- 架構決策記錄模板（Architecture Decision Record Template） [9]
- 事故分析模板（Incident Postmortem Template） [10]
- DevOps執(zhí)行手冊（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做過研發(fā)，現(xiàn)在在Mavenir做技術工作，對通信、網(wǎng)絡、后端架構、云原生、DevOps、CICD、區(qū)塊鏈、AI等技術始終保持著濃厚的興趣，平時喜歡閱讀、思考，相信持續(xù)學習、終身成長，歡迎一起交流學習。
當前文章：軟件工程師文檔寫作優(yōu)秀實踐
本文URL：http://www.5511xx.com/article/dpdodse.html
