Fwd: Architectural Decision Records for spec development

Dear TAG,

A few weeks ago, I sent this open question to the  W3C editors spec-prod
mailing list; it didn't get any feedback on the list, but I had some
interesting follow up discussions at TPAC last week with a couple of
people interested in exploring that methodology.

Since it probably intersects strongly with some of the needs for the TAG
(for instance, the encouragement to document "tricky design decisions"
as part of the explainer), I thought I would bring attention to this
idea here as well.


-------- Message transféré --------
Sujet : Architectural Decision Records for spec development
Date de renvoi : Wed, 03 Jul 2019 08:41:58 +0000
De (renvoi) : spec-prod@w3.org
Date : Wed, 3 Jul 2019 10:41:54 +0200
De : Dominique Hazael-Massieux <dom@w3.org>
Pour : spec-prod <spec-prod@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, 25 September 2019 09:25:26 UTC