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

转载 2017年11月27日 00:00:00

是的,我又写了一个 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 的库。

它的安装很简单:

  1. npm install -g adr

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

  1. adr new 'hello, world'

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

  1. $ adr list

  2. ╔══════════════════════════════════════╤══════════════╤═══════════════════╗

  3. ║ 决策                                 │ 上次修改时间    │ 最后状态          ║

  4. ╟──────────────────────────────────────┼──────────────┼───────────────────╢

  5. 1.编写完整的单元测试                 │ 2017-11-27   │ 2017-11-26 已完成 ║

  6. ╟──────────────────────────────────────┼──────────────┼───────────────────╢

  7. 2.添加目录生成                       │ 2017-11-27   │ 2017-11-25 已完成 ║

  8. ╟──────────────────────────────────────┼──────────────┼───────────────────╢

  9. 3.图形生成功能                       │ 2017-11-27   │ 2017-11-24 已完成 ║

  10. ╟──────────────────────────────────────┼──────────────┼───────────────────╢

  11. 4.生成在线图形                       │ 2017-11-27   │ 2017-11-22 提议   ║

  12. ...

  13. ╟──────────────────────────────────────┼──────────────┼───────────────────╢

  14. 15.考虑添加-export-功能来导出-adr    │ 2017-11-27   │ 2017-11-26 提议   ║

  15. ╟──────────────────────────────────────┼──────────────┼───────────────────╢

  16. 16.使用不同色彩来标注不同的状态      │ 2017-11-27   │ 2017-11-27 提议   ║

  17. ╚══════════════════════════════════════╧══════════════╧═══════════════════╝

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

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

  1. $ git logs 9

  2. ╔════════════╤══════╗

  3. ║  -         │  -   ║

  4. ╟────────────┼──────╢

  5. 2017-11-23 │ 提议  ║

  6. ╟────────────┼──────╢

  7. 2017-11-23 │ 通过  ║

  8. ╚════════════╧══════╝

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

  • 内置 update 命令,方便同步决策到标题上

  • 生成决策的目录,方便快速定位

  • 支持导出 CSV 格式,以便在 Excel 中查看

  • 支持导出 JSON 格式,以便进行二次开发


有赞赏码了~~

0?wx_fmt=jpeg


欢迎大家试用和参与

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

点击阅读原文访问

2017年技术、平台、工具、语言&架构

技术、平台、工具、语言&框架,年底应该这样把握技术方向! 原创 2017-12-01 ThoughtWorks InfoQ 作者|ThoughtWorks编辑|小智ThoughtWorks ...
  • wuxiaobingandbob
  • wuxiaobingandbob
  • 2017年12月01日 08:49
  • 71

Delta - 轻量级JavaWeb框架使用文档

Delta 是一个基于MVC架构的轻量级WEB开发框架,基于jdk1.8开发,目前最新版本更新为 delta_1.1_beta,项目完全开源,并提供包装后的jar包方便用户快速开发。...
  • u012260293
  • u012260293
  • 2015年12月24日 16:58
  • 7509

老黄聊架构:微服务架构落地之前,需要想清楚的几个关键问题

自从 2014 年“微服务架构”这个概念首次提出以来,在业界就引发了一股对微服务架构的激烈探讨,大家对它的意义褒贬不一,所以我想借此机会给大家简单分享一下我所理解的微服务架构,主要内容会包括:为什么需...
  • penker_zhao
  • penker_zhao
  • 2016年04月12日 13:27
  • 3848

java中重量级和轻量级的区别

首先轻量级与重量级是一个相对的概念,主要是对应用框架使用方便性和所提供服务特性等方面做比较的。 重量级的框架在耦合性方面要比轻量级的大一些,但是重量级框架提供的服务要比轻量级的多。 比方说EJ...
  • chenyuanyong110
  • chenyuanyong110
  • 2016年05月16日 16:13
  • 1240

钱柜娱乐开户 轻量级的友好的交互对话框库,EasyDialog,实现已详细标注

转载请注明出处:王亟亟的大牛之路Git上看到的一个蛮清爽的一个Dialog介绍给大家,Git地址 实现效果 个人感觉做的还是满Q弹的 如何使用? compile 'com.github.mi...
  • ddwhan0123
  • ddwhan0123
  • 2015年08月31日 16:43
  • 2056

SDRMS 基于Beego开发的易用、易扩展、界面友好的轻量级功能权限管理系统

简介SDRMS是基于Beego开发的易用、易扩展、界面友好的轻量级功能权限管理系统。前端框架基于AdminLTE2进行资源整合,包含了多款优秀的插件,是笔者对多年后台管理系统开发经验精华的萃取。 本系...
  • lhtzbj12
  • lhtzbj12
  • 2017年12月19日 21:53
  • 981

钱柜娱乐开户 轻量级的友好的交互对话框库,EasyDialog,实现已详细标注

实现效果    个人感觉做的还是满Q弹的  如何使用? compile 'com.github.michaelye.easydialog:easydialog:1.4' 1 其...
  • xiaoqun999
  • xiaoqun999
  • 2017年11月29日 11:07
  • 33

使用Abiword/Gobby进行局域网轻量级文档协作编辑

昨天有个同学问我如何进行局域网文档协作编辑,SharePoint当然是不二人选——虽然我并未用过,但是复杂的安装配置显然不能满足他立即解决问题的需求,经过搜索,发现了AbiWord和Gobby这两个能...
  • nudtcadet
  • nudtcadet
  • 2011年12月19日 00:59
  • 2533

韩顺平_轻松搞定网页设计(html+css+javascript)_第30讲_类和对象细节_创建对象的几种方式_js对象内存分析_学习笔记_源代码图解_PPT文档整理

文西马龙:/wenximalong/ 对象——function特别说明 1.在js中一切都是对象 2.类(原型对象)其实也是对象,它实际上是Functio...
  • wenximalong
  • wenximalong
  • 2012年12月07日 12:01
  • 3344

教你方便使用ASDoc《双击轻松生成API文档》

用过ASDoc的同学都知道,使用ASDoc需要先去打开Adobe放在开始菜单中的Adobe Flex 3 SDK Command Prompt文件 然后在打开的cmd窗口中输入命令 比如这样: ...
  • txiejun
  • txiejun
  • 2011年12月06日 16:36
  • 542
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:使用 adr 轻松创建 “程序员友好” 的轻量级文档
举报原因:
原因补充:

(最多只允许输入30个字)