W3C home > Mailing lists > Public > spec-prod@w3.org > July to September 2019

Architectural Decision Records for spec development

From: Dominique Hazael-Massieux <dom@w3.org>
Date: Wed, 3 Jul 2019 10:41:54 +0200
To: spec-prod <spec-prod@w3.org>
Message-ID: <2269a12d-e865-04d3-bb42-1815d1ea1a6e@w3.org>
Hi spec-prod,

My path has crossed Architectural Decision Records (ADR) a few times in
the past few months:

ADR are basically a way to formally document architectural decision
(i.e. significant design choices) - I wonder if any W3C group has had
experience using this mechanism or something similar?

My impression is that many groups make a lot of these decisions which
get recorded in a mix of meeting minutes, github issues, github pull
requests, git commits, spec notes, but that there is no easy way to list
and extract these significant decisions, nor a formal approach to
describing them (ADR typically asks to document context and consequences
alongside with the actual decision).

My further impression is that having a more formal approach to record
and track these decisions could prove useful in a number of cases:
* easing onboarding of new contributors, esp new editors
* review of design choices e.g. by the TAG
* ease of refactoring of a spec in its maintenance phase

I would be interested to see if groups have existing best practices in
this field that we could help gain broader adoption.

Received on Wednesday, 3 July 2019 08:41:57 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:23 UTC