使用 adr 轻松创建 “程序员友好” 的轻量级文档

是的,我又写了一个 markdown 工具,它对我来说非常有用。

上下文

在一周里,我看到了一个名为 “轻量级架构决策记录” 的技术实践。在看到了一个简单的示例之后,并阅读了文章《架构决策记录》之后,我开始对于这种工具有了一个好的印象。这似乎就是我,以及敏捷团队、程序员所梦寐以求的工具。

作为一个程序员,我们并不喜欢阅读又长又臭的文档,它往往不如一个 hello, world 来得实在。更不用说自己去写一个又长又臭的的文档了。事实上,我们对于文档的痛恶的原因是:文档经常是落后的、老旧的。因此,一个更合适的方案是,创建一种轻量级的文档。

作为程序员,我们常说代码即文档。是的,代码本身是文档的一部分,但是代码往往告诉你的是结果代码不会告诉你原因。尽管从版本控制中,我们仍能通过 log 找到对应的 Author,可往往找到的这个人,可能已经没有人认识了(至少隔了一代开发人员)。

因此,如《架构决策记录》一文中所说:

项目在其生命周期中,最难追踪的事情之一就是:某些技术决策背后的动机

这时,我们往往需要一个工具来记录产生这些技术决策的原因。

随后通过 ThoughtWorks 技术雷达(在 2016.11 期上提到 ADR),我找到了一个相关的库:adr-tools,但是发现这个库有一些小的缺点:

  • 使用 shell 编写,不易读懂、只支持类 Unix;
  • 模板里使用的是英语,不支持中文及其他语言

决策

于是,我便决定自己写一个这样的工具。它应该采用 markdown,并使用《架构决策记录》一文中提到的格式:

标题,这些文件的名称是短名词短语。例如,“ADR 1: Deployment on Ruby on Rails 3.0.10” 或 “ADR 9: LDAP for Multitenant Integration

上下文,这一节描述了当前的技术、政治、社会和项目。这些力量可能处于紧张状态,应该这样说。本节中的语言是价值中立的,只用于描述事实

决策,这一节描述我们对这些力量的回应。这是充分的句子,以及积极的声音。 “我们会...”

状态,如果项目利益相关方尚未同意,或者一旦达成一致,则 “决定” 可能被 “提议”。如果以后的 ADR (架构决策记录)更改或撤消决定,则可能会将其标记为 “已弃用” 或 “已取代”,并参考其替换。

后果,这部分描述了应用决策后产生的上下文。所有的后果应该列在这里,而不仅仅是 “积极的”。一个特定的决策可能会产生积极的、消极的和中性的后果,但是它们都会影响未来的团队和项目。

并且,它应该可以轻松地实现:

  • 采用一种能用的语言环境,如 Node.js,以支持主流的操作系统
  • 多语言支持,我的意思是它至少可以支持 English 和 中文
  • 支持状态日志查询,即我应该可以看到一个决策在生命周期里的变化
  • 一个更好的列表展示,我应该可以查看到某条决策,以及对应的最后状态、修改时间等等
  • 使用 markdown 展示,以便在 GitHub 上显示
  • 拥有一个 ToC 页面,方便用户查看

状态

2017-11-22 提议

2017-11-22 通过

2017-11-22 完成第一个版本

结果

最后,我使用 TypeScript 与 Node.js 创建了一个 adr.js 的库。

它的安装很简单:

npm install -g adr

然后,你就可以创建你的 ADR 了:

adr new 'hello, world'

并结合提供的工具来查看这些技术决策:

$ adr list╔══════════════════════════════════════╤══════════════╤═══════════════════╗║ 决策                                 │ 上次修改时间    │ 最后状态          ║╟──────────────────────────────────────┼──────────────┼───────────────────╢║ 1.编写完整的单元测试                 │ 2017-11-27   │ 2017-11-26 已完成 ║╟──────────────────────────────────────┼──────────────┼───────────────────╢║ 2.添加目录生成                       │ 2017-11-27   │ 2017-11-25 已完成 ║╟──────────────────────────────────────┼──────────────┼───────────────────╢║ 3.图形生成功能                       │ 2017-11-27   │ 2017-11-24 已完成 ║╟──────────────────────────────────────┼──────────────┼───────────────────╢║ 4.生成在线图形                       │ 2017-11-27   │ 2017-11-22 提议   ║...╟──────────────────────────────────────┼──────────────┼───────────────────╢║ 15.考虑添加-export-功能来导出-adr    │ 2017-11-27   │ 2017-11-26 提议   ║╟──────────────────────────────────────┼──────────────┼───────────────────╢║ 16.使用不同色彩来标注不同的状态      │ 2017-11-27   │ 2017-11-27 提议   ║╚══════════════════════════════════════╧══════════════╧═══════════════════╝

不过,在这里我犯了一个错误,就是把功能需求也放到里面了。

我们也可以查看某个决策在生命周期的变化:

$ git logs 9╔════════════╤══════╗║  -         │  -   ║╟────────────┼──────╢║ 2017-11-23 │ 提议  ║╟────────────┼──────╢║ 2017-11-23 │ 通过  ║╚════════════╧══════╝

除了这些,还有额外的功能:

  • 内置 update 命令,方便同步决策到标题上
  • 生成决策的目录,方便快速定位
  • 支持导出 CSV 格式,以便在 Excel 中查看
  • 支持导出 JSON 格式,以便进行二次开发

有赞赏码了~~

项目 GitHub 地址:https://github.com/phodal/adr

原文发布于微信公众号 - phodal(phodal-weixin)

原文发表时间:2017-11-27

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏福利活动清单

新用户有哪些优惠——腾讯云篇

满200减150 / 满500减375 / 满1000减750 / 满2000减1500

1.7K20
来自专栏ImportSource

服务之美-读《微服务设计》笔记全集(一)

最近在微信读书上读《微服务设计》一书,目前读了30%多了,其间想法有点多,现分享给大家。

15520
来自专栏程序员互动联盟

【答疑释惑】学嵌入式需要什么样的电脑配置?

毋庸置疑,嵌入式仍旧是一门非常热门的技术,每年依旧有很多同学投入到嵌入式学习的大军中来。从简单的8位单片机,例如51系列,到32位的arm,mips系列,甚至现...

38280
来自专栏后端技术探索

Uber工程技术栈(二):看曾经的独角兽背后用了哪些技术

我们的服务彼此交互,还与移动设备进行交互,而那些交互对业务状况(比如动态定价)和内部使用(比如调试)来说都很重要。就日志而言,我们使用了多个Kafka集群,数据...

9840
来自专栏FreeBuf

如何在网络中追踪入侵者(一):架构

背景知识 由于依赖感染指标(IOCs)的安全方法越来越不可靠,“突破口假设”成为业界公共的表示方法。这种情况经常发生,直到外部主机发现一个缺口并通知机构之前,入...

261100
来自专栏小文博客

Vultr推出新套餐——3.5$/月,有IPV4地址

今天突然发现vultr多了一个3.5$的套餐,仔细看了下,配置和2.5$的一样,唯一区别就是有IPV4地址,可以说对于那些科学上网的朋友是个天大的好消息!

57420
来自专栏java学习

为什么一定要前后端分离?

原文: http://www.cnblogs.com/rjzheng/p/9185502.html

21510
来自专栏数据和云

遇见未来 | PostgreSQL:一匹即将发力的黑马

在2017年的DB-Engine的年度数据库榜单上,PostgreSQL以其超过其他341个受监控数据库管理系统的受欢迎程度居于榜首,被评为年度DBMS。其总体...

73670
来自专栏鹅厂网事

腾讯网络应对闰秒危机之最佳实践

"鹅厂网事"由深圳市腾讯计算机系统有限公司技术工程事业群网络平台部运营,我们希望与业界各位志同道合的伙伴交流切磋最新的网络、服务器行业动态信息,同时分享腾讯在网...

27850
来自专栏程序你好

个人门户系统设计方案

42440

扫码关注云+社区

领取腾讯云代金券