作为软件工程师,掌握编写高质量文档的技能非常重要,特别是由于最近远程工作的增加,在异步通信方面就需要做得更好。作为远程工作的实践者,GitLab在定义异步沟通[2]方面做得很好: “异步沟通是一种沟通的艺术,无需在发送公开报告的同时让所有相关方都到场,也可以推进项目向前。” 高质量的文档是实现有效异步沟通的简单方式。在这篇文章中,我将讨论一些在个人经历中非常有用的有趣的技巧。 谷歌技术写作课程 谷歌为软件工程师提供了免费的技术写作课程。课程从技术写作的基础部分开始,分为两个部分,内容如下: 谷歌技术写作1 谷歌技术写作2 没人能够在一夜之间就擅长技术写作,这需要反复练习。我个人更喜欢每个月都去学习一下这门课程,以提醒自己什么才是写作的最佳实践。 使用Divio文档框架 在所有文档框架中,我个人最喜欢Divio[3]。这里建议的文档系统非常简单并且普遍适用。 该框架建议将文档分类如下: 教程(Tutorials)—— 面向学习的 指南(How-To Guides)—— 面向问题解决的 解释(Explanation)—— 面向理解的 索引(Reference)—— 面向信息的 该方案被许多著名开源项目和企业广泛采用[4]。 youtube上有一个很好的视频,详细解释了框架的细节:https:///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:///best-practices-when-documenting-your-code-for-software-engineers-941f0897aa0 [2] How to embrace asynchronous communication for remote work:https://about./company/culture/all-remote/asynchronous/ [3] Divio:https://www./ [4] Who is using the system:https://documentation./adoption/#adoption [5] Mastering Markdown:https://guides.github.com/features/mastering-markdown/ [6] Mermaid:http://mermaid-js./mermaid/ [7] Mermaid Live Editor:https://mermaid-js./mermaid-live-editor/ [8] Software Architecture Review Template:https://www./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./software/confluence/templates/incident-postmortem [11] DevOps Runbook:https://www./software/confluence/templates/devops-runbook [12] Decision Template:https://www./software/confluence/templates/decision [13] Writing Guidelines:https://www./software/confluence/templates/writing-guidelines [14] OKR Template:https://www./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 转自:DeepNoMind |
|
来自: ThinkfunQd > 《待分类》