社区编辑申请
注册/登录
软件工程师文档写作优秀实践
开发 新闻
高质量的文档是实现有效异步沟通的简单方式。在这篇文章中,我将讨论一些在个人经历中非常有用的有趣的技巧。

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

作为软件工程师,掌握编写高质量文档的技能非常重要,特别是由于最近远程工作的增加,在异步通信方面就需要做得更好。作为远程工作的实践者,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 Engineershttps://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
相关推荐

2022-06-20 22:37:25

Linux操作系统命令

2022-06-15 11:51:14

Vue3开发避坑

2022-06-15 08:21:49

Linux运维工程师

2022-06-27 17:46:53

PythonFlask

2022-06-07 09:59:21

网络安全安全漏洞

2022-07-01 18:24:36

勒索软件病毒网络攻击

2022-06-30 18:17:00

数据集云数据建模计数据仓库

2022-06-15 09:01:41

2022-06-30 10:56:18

字节云数据库存储

2022-07-01 14:14:42

MuddyWater攻击伊朗

2022-06-24 10:52:47

人工智能作业帮T前线

2022-06-03 09:41:03

DockerKubernetes容器

2022-03-11 18:30:39

DevOps软件开发

2022-06-16 15:54:32

前端

2022-06-16 15:42:16

攻击面管理ASM

2022-06-24 11:14:00

美团开源

2022-06-17 12:10:07

RPA机器人流程自动化

2022-07-01 11:12:53

联想

2022-06-28 10:03:56

CentOSLinux

2022-06-16 07:32:38

VSCodePython插件

同话题下的热门内容

手把手教你用装饰器扩展 Python 计时器吐血推荐17个提升开发效率的“轮子”裁员真能拯救中国互联网?监控Kubernetes的最佳实践、工具和方法哪些编程语言会在Web 3时代脱颖而出?IOC-Golang 的 AOP 原理与应用跨区域、Kubernetes集群运行数据库实践指南并发编程的三大核心问题

编辑推荐

2017年9月编程语言排行榜:Java、C与C++三巨头还能统治排行榜多久?2017年最受欢迎的5个前端框架比较2017年11月编程语言排行榜:脚本语言怎么了?2017年3月编程语言排行榜:Swift首次进入前十最近租房有点烦!技术人如何用Python找到称心如意的“小窝”?
我收藏的内容
点赞
收藏

51CTO技术栈公众号