软件工程师文档写作最佳实践

对于软件工程师来说，文档写作是团队合作和沟通的必备技能，特别是在远程工作越来越流行的后疫情时代，文档的重要性愈发重要。这篇文章分享了很多能够帮助开发者提升文档能力的资源，帮助我们写出更好更容易维护的文档。原文：Best Practices When Documenting Your Code for Software Engineers^[1]

来源-https://undraw.co/

作为软件工程师，掌握编写高质量文档的技能非常重要，特别是由于最近远程工作的增加，在异步通信方面就需要做得更好。作为远程工作的实践者，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 等技术始终保持着浓厚的兴趣，平时喜欢阅读、思考，相信持续学习、终身成长，欢迎一起交流学习。

微信公众号：DeepNoMind