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

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

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

image.png

来源-https://undraw.co/


作为软件工程师,掌握编写高质量文档的技能非常重要,特别是由于最近远程工作的增加,在异步通信方面就需要做得更好。作为远程工作的实践者,GitLab 在定义异步沟通[2]方面做得很好:


“异步沟通是一种沟通的艺术,无需在发送公开报告的同时让所有相关方都到场,也可以推进项目向前。”


高质量的文档是实现有效异步沟通的简单方式。在这篇文章中,我将讨论一些在个人经历中非常有用的有趣的技巧。


谷歌技术写作课程


谷歌为软件工程师提供了免费的技术写作课程。课程从技术写作的基础部分开始,分为两个部分,内容如下:

image.png

谷歌技术写作 1

image.png

谷歌技术写作 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 创建的示例图:


image.png

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


目录
相关文章
|
7月前
|
算法 测试技术 开发工具
编写高效技术文档的艺术:C++项目实践指南
编写高效技术文档的艺术:C++项目实践指南
177 0
|
6月前
|
存储 边缘计算 Cloud Native
“论模型驱动架构设计方法及其应用”写作框架,软考高级,系统架构设计师
模型驱动架构设计是一种用于应用系统开发的软件设计方法,以模型构造、模型转换和精化为核心,提供了一套软件设计的指导规范。在模型驱动架构环境下,通过创建出机器可读和高度抽象的模型实现对不同问题域的描述,这些模型独立于实现技术,以标准化的方式储存,利用模型转换策略来驱动包括分析、设计和实现等在内的整个软件开发过程。
343 3
|
5月前
|
机器学习/深度学习 Kubernetes 云计算
技术文档工程师和技术翻译
- 阿里云智能集团招聘技术岗,位于杭州和北京。 - 技术文档工程师岗位要求包括独立编写代码能力、快速学习新技术、简化复杂技术概念、扎实的技术理解和良好的时间管理。 - 翻译工程师还需具备相关学历背景、技术翻译经验和云产品知识。 **团队成员分享:** - 昱心(南洋理工大学,机器学习)和骞腾(UIUC,计算机科学)分享了他们在技术文档岗位上的成长,涉及大模型和K8S等技术。 - 舟预(北京交通大学,信息管理)强调技术文档的重要性,认为它是阿里云对外的权威发言人。 - 天蒙(南开大学,信息与通信工程)提到工作中与代码的紧密联系,团队支持技术成长。
23880 24
技术文档工程师和技术翻译
|
7月前
|
项目管理
技术方案撰写之道:实用技巧与方法
本文探讨了如何撰写技术方案,强调了考虑方案的相关方、关键指标、目标受众和预期收益的重要性。文章提出了写作框架应清晰、表达生动、具有美感,并指出好的方案应实现共赢、系统规划和显著效益。写技术方案时,需明确问题、深入分析需求、设定合理目标、设立度量标准、专业设计方案、规划执行路径并有效项目管理,确保方案的成功实施和收益。
649 0
|
程序员 测试技术 API
程序员不撰写代码注释和文档的十大理由
在软件开发的世界中,撰写代码注释和文档通常被认为是一项重要的工作,它可以帮助其他开发者理解你的代码,更容易地维护和扩展它。然而,在实际操作中,很多程序员却选择不写注释或文档。以下列出了程序员们在实践中经常提到的十大理由,这些理由不仅揭示了他们对于撰写文档和注释的观点,也反映出软件开发行业中一些深层次的问题。
165 1
程序员不撰写代码注释和文档的十大理由
|
人工智能 自然语言处理 机器人
ChatGPT初学者最佳实践
2022年11月底,ChatGPT引爆了新一轮AI的革命,也让人们意识到AI真的能够大幅度提高人们的工作效率,甚至有人担心自己的工作会因为AI不保。这种居安思危的意识是正确的,但是正如锛凿斧锯的出现,并没有让木匠这个行业消失,而是让这个行业以更高效的方式工作。所以作为一种工具,我们应当对ChatGPT有一个正确认知,我们不要把自己定位成ChatGPT,而是要站在更为宏观的角度上,将自己定位成利用工具的人,才不会出现被AI淘汰的局面。 那么如何才能更好的利用chatGPT呢?为什么同时利用这种工具,有的人效率高,有的人却感觉没什么用呢?秘密就在如何写好提示词上,本文通过一些最佳实践,帮助大家更
196 0
|
SQL 数据挖掘 项目管理
如何用ChatGPT做项目管理?
ChatGPT可以通过创建和维护跨团队项目协作计划,让员工更容易理解他们的角色和职责。这个协作计划里面会包括每个团队或个人要执行的具体任务,每个任务最后期限和任何事情之间的依赖关系。
515 0
|
存储 Java 程序员
如何写好技术文档——来自Google十多年的文档经验
如何写好技术文档——来自Google十多年的文档经验
572 2
如何写好技术文档——来自Google十多年的文档经验
|
敏捷开发 架构师 程序员
【干货合集】12篇文章带你读懂敏捷架构!
流行技术大狂欢,5月29日即将召开的第二届研发效能嘉年华,带来了前沿技术理念及实践技术成果分享。本次峰会将有10位技术大咖进行干货分享,多角度,不同领域的带领大家了解高效研发。
7906 0
略谈为什么要重视文档写作
略谈为什么要重视文档写作
200 0
略谈为什么要重视文档写作