软件工程师文档写作最佳实践
对于软件工程师来说，文档写作是团队合作和沟通的必备技能，特别是在远程工作越来越流行的后疫情时代，文档的重要性愈发重要。这篇文章分享了很多能够帮助开发者提升文档能力的资源，帮助我们写出更好更容易维护的文档。原文：Best Practices When Documenting Your Code for Software Engineers
作为软件工程师，掌握编写高质量文档的技能非常重要，特别是由于最近远程工作的增加，在异步通信方面就需要做得更好。作为远程工作的实践者，GitLab在定义异步沟通方面做得很好：
“异步沟通是一种沟通的艺术，无需在发送公开报告的同时让所有相关方都到场，也可以推进项目向前。”
高质量的文档是实现有效异步沟通的简单方式。在这篇文章中，我将讨论一些在个人经历中非常有用的有趣的技巧。
谷歌技术写作课程
谷歌为软件工程师提供了免费的技术写作课程。课程从技术写作的基础部分开始，分为两个部分，内容如下：
没人能够在一夜之间就擅长技术写作，这需要反复练习。我个人更喜欢每个月都去学习一下这门课程，以提醒自己什么才是写作的最佳实践。
使用Divio文档框架
在所有文档框架中，我个人最喜欢Divio。这里建议的文档系统非常简单并且普遍适用。
该框架建议将文档分类如下：
教程（Tutorials）—— 面向学习的
指南（How-To Guides）—— 面向问题解决的
解释（Explanation）—— 面向理解的
索引（Reference）—— 面向信息的
该方案被许多著名开源项目和企业广泛采用。
使用基于markdown的文档系统
在传统企业中，可以使用各种方法来维护文档。有些人喜欢创建MS Word/Excel文档，然后上传到SharePoint或OneDrives中。此类文档最大问题是，无法使用内部搜索引擎进行搜索。因此，我个人更喜欢使用基于markdown的文档系统。创建和维护这类文档很容易，并且文档是可搜索的。
如果你还不熟悉Markdown，可以查看GitHub上的免费课程，轻松掌握这个工具。
使用Mermaid JS作图
根据Mermaid的说法，这是“一个基于javascript的图形和图表工具，使用类似markdown的文本定义和渲染器来创建和修改复杂的图表。”如果使用GitLab或Azure DevOps，原生就支持了Mermaid，如果使用GitHub或Atlassian的产品，那么可以通过插件使用。
使用Mermaid创建和更新图表非常容易，不需要给每个开发人员安装Visio/draw.io这样的UML工具。
下面是一些用Mermaid创建的示例图：
可以立即尝试使用Mermaid Live Editor创建图表。
使用模板
像Confluence这样的网站上有很多模板，可以用于特定类型的文档。例如：
软件架构评审模板（Software Architecture Review Template）
架构决策记录模板（Architecture Decision Record Template）
事故分析模板（Incident Postmortem Template）
DevOps执行手册（DevOps Runbook）
决策模板（Decision Template）
写作指南（Writing Guidelines）
OKR模板（OKR Template）
等等
参考风格指南（Style Guides）
如果你的团队还没有风格指南，可以参考一下谷歌和微软的做法：
Microsoft Style Guide
Google Developer Documentation Style Guide
References:
[1] Best Practices When Documenting Your Code for Software Engineers:
[2] How to embrace asynchronous communication for remote work:
[8] Software Architecture Review Template:
你好，我是俞凡，在Motorola做过研发，现在在Mavenir做技术工作，对通信、网络、后端架构、云原生、DevOps、CICD、区块链、AI等技术始终保持着浓厚的兴趣，平时喜欢阅读、思考，相信持续学习、终身成长，欢迎一起交流学习。
微信公众号：DeepNoMind