对于软件工程师来说，文档写作是团队合作和沟通的必备技能，尤其是在远程工作越来越流行的后疫情时代，文档的重要性越来越高越来越重要。本文分享了很多资源，可以帮助开发者提高他们的文档能力，帮助我们写出更好更容易维护的文档。原文：BestPracticesWhenDocumentingYourCodeforSoftwareEngineers[1]作为一名软件工程师，拥有编写高质量文档的技能非常重要，特别是由于最近远程工作的增加，你需要在异步通信。作为远程工作的实践者，GitLab很好地定义了异步通信[2]：“异步通信是一种通信艺术，可以在发送公开报告时无需所有相关方在场的情况下推进项目。前。”高质量的文档是实现有效异步通信的简单方法。在本文中，我将讨论一些有趣的技术，这些技术在我的个人经历中非常有用。Google技术写作课程Google为软件工程师提供免费的技术写作课程。课程从技术写作的基础开始，分为以下两部分：GoogleTechnicalWriting1GoogleTechnicalWriting2没有人可以在一夜之间成为擅长技术写作的人，它需要练习和练习。我个人更喜欢每个月都参加这门课程，以提醒自己什么是写作的最佳实践。使用Divio文档框架在所有文档框架中，Divio[3]是我个人最喜欢的。这里建议的文档系统非常简单并且普遍适用。该框架建议将文档分类如下：Tutorials-How-ToGuides-Problem-Solving-OrientedExplanation-Comprehension-OrientedIndexes(Reference)-Information-OrientedSolutions被许多著名的开源项目和企业广泛采用[4]。youtube上有一个很好的视频详细解释了框架的细节：https://youtu.be/t4vKPhjcMZg使用基于markdown的文档系统在传统企业中，可以使用各种方法来维护文档。有些人喜欢创建MSWord/Excel文档并将它们上传到SharePoint或OneDrives。此类文档的最大问题是无法使用内部搜索引擎进行搜索。因此，我个人更喜欢使用基于markdown的文档系统。创建和维护此类文档很容易，并且可以搜索文档。如果您还不熟悉Markdown，可以查看GitHub上的免费课程[5]来轻松掌握这个工具。使用MermaidJS绘图根据Mermaid[6]的说法，它是“一种基于javascript的绘图和图表工具，使用类似markdown的文本定义和渲染器来创建和修改复杂的图表。”如果使用GitLab或AzureDevOps，则原生支持Mermaid，如果使用GitHub或Atlassian产品，则可以通过插件使用。使用Mermaid创建和更新图表非常容易，无需为每个开发人员安装Visio/draw.io等UML工具。以下是使用Mermaid创建的一些示例图：MermaidSequenceDiagram示例MermaidClassDiagram示例立即尝试使用MermaidLiveEditor[7]创建图表。使用模板像Confluence这样的站点有许多模板可以用于特定类型的文档。例如：SoftwareArchitectureReviewTemplate[8]ArchitectureDecisionRecordTemplate[9]IncidentPostmortemTemplate[10]DevOpsRunbook[11]DecisionTemplate（决策模板）[12]WritingGuidelines（写作指南）[13]OKRTemplate（OKRTemplate）[14]等参考风格指南（StyleGuides）如果你的团队没有风格指南，可以参考谷歌和微软的做法：微软风格指南[15]谷歌开发者文档风格指南[16]参考资料：[1]为软件工程师编写代码文档的最佳实践：https://betterprogramming.pub/best-practices-when-documenting-your-code-for-software-engineers-941f0897aa0[2]如何为远程应用程序采用异步通信作品：https://about.gitlab.com/company/culture/all-remote/asynchronous/[3]Divio：https://www.divio.com/[4]谁在使用系统：https://documentation.divio.com/adoption/#adoption[5]掌握Markdown：https://guides.github.com/features/mastering-markdown/[6]Mer女仆：http://mermaid-js.github.io/mermaid/[7]美人鱼直播编辑器：https://mermaid-js.github.io/mermaid-live-editor/[8]软件架构审查模板：https://www.atlassian.com/software/confluence/templates/software-architecture-review[9]轻量级架构决策记录：https://github.com/deshpandetanmay/lightweight-architecture-decision-records/blob/master/doc/adr/0001-use-elasticsearch-for-search-api.md[10]事件事后分析：https://www.atlassian.com/software/confluence/templates/incident-postmortem[11]DevOpsRunbook：https://www.atlassian.com/software/confluence/templates/devops-runbook[12]决策模板：https://www.atlassian.com/software/confluence/templates/decision[13]写作指南：https://www.atlassian.com/software/confluence/templates/writing-guidelines[14]OKR模板：https://www.atlassian.com/software/confluence/templates/writing-guidelinesatlassian.com/software/confluence/templates/okrs[15]微软风格指南：https://docs.microsoft.com/en-us/style-guide/[16]谷歌开发者文档风格指南：https://developers.google.co你好m/style，我是于凡。我在摩托罗拉做过研发，现在在Mavenir做技术工作。兴趣浓厚，平时喜欢读书、思考，相信不断学习，终生成长，欢迎一起交流学习
