From 87985a70aba5c0441312baa35c283a6cd1b38bb6 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Thu, 9 Apr 2026 17:51:52 -0700 Subject: [PATCH 1/4] Recommend two structures for organizing alternatives considered. --- index.bs | 31 ++++++++++++++++++++++++++++++- template.md | 31 +++++++++++++++++++++++++++---- 2 files changed, 57 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 355517b..4b0965c 100644 --- a/index.bs +++ b/index.bs @@ -152,7 +152,36 @@ If your proposed design depends on other non-consensus features, list them. As your design evolves, keep track of and make a note of alternatives which have been considered. Explain what makes them worse for the web than your primary proposal. -You undoubtedly had reasons not to choose those alternatives, but reviewers and other stakeholders may not have that context. Avoid redundant "what about [already-ruled out alternative]" type questions by explaining why those alternatives were ruled out. +You undoubtedly had reasons not to choose those alternatives, +but reviewers and other stakeholders may not have that context. +Avoid redundant "what about [already-ruled out alternative]" type questions by explaining why those alternatives were ruled out. + +Format the alternatives in a way that makes them easy to understand. +There are a few ways to do this. +First, you can structure the alternative as: + +```markdown +### Name of the alternative + +Explanation of the alternative design. + +#### Pros + +* List + +#### Cons + +* List + +#### Reason for rejection + +Why do you feel the pros outweigh the cons? +``` + +Alternatively, you can collect a set of [Architectural Decision Records](https://adr.github.io/) as files in your repository. +[https://adr.github.io/madr/](https://adr.github.io/madr/#overview) may contain a good template, +but we don't have enough experience to recommend this structure in particular. +If you have a directory of ADRs, link them from this section of your explainer. ## Connect to History ## {#history} diff --git a/template.md b/template.md index a9364bd..e5a22dc 100644 --- a/template.md +++ b/template.md @@ -85,18 +85,41 @@ group), list them here.] ## Alternatives considered [This should include as many alternatives as you can, -from high level architectural decisions down to alternative naming choices.] +from high level architectural decisions down to alternative naming choices. +If you capture your alternatives as Architectural Decision Records, +use this section to link to the ADRs.] ### [Alternative 1] -[Describe an alternative which was considered, -and why you decided against it. +[Describe an alternative which was considered. This alternative may have been part of a prior proposal in the same area, or it may be new. -If you did any research in making this decision, discuss it here.] +If you did any research in evaluating this alternative, discuss it here.] + +#### Pros + +* [List] + +#### Cons + +* [List] + +#### Reason for rejection + +[Why do you feel the pros outweigh the cons?] ### [Alternative 2] +#### Pros + +* [List] + +#### Cons + +* [List] + +#### Reason for rejection + [You may not have decided about some alternatives. Describe them as open questions here, and adjust the description once you make a decision.] From 7f674467b6ec96b28b0751cf206f352fb7c394a8 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Thu, 23 Apr 2026 17:19:41 -0700 Subject: [PATCH 2/4] The reason for rejection had pros and cons backwards. --- index.bs | 2 +- template.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 4b0965c..d5bff3c 100644 --- a/index.bs +++ b/index.bs @@ -175,7 +175,7 @@ Explanation of the alternative design. #### Reason for rejection -Why do you feel the pros outweigh the cons? +Why do you feel the cons outweigh the pros? ``` Alternatively, you can collect a set of [Architectural Decision Records](https://adr.github.io/) as files in your repository. diff --git a/template.md b/template.md index e5a22dc..4049e68 100644 --- a/template.md +++ b/template.md @@ -106,7 +106,7 @@ If you did any research in evaluating this alternative, discuss it here.] #### Reason for rejection -[Why do you feel the pros outweigh the cons?] +[Why do you feel the cons outweigh the pros?] ### [Alternative 2] From fe4f9eaada0f401c454fb24282be6dc2a63497df Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Thu, 23 Apr 2026 17:19:41 -0700 Subject: [PATCH 3/4] Allow explainers to quickly dismiss alternatives that are clearly unacceptable. Thanks to David Baron for pointing this out. --- index.bs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/index.bs b/index.bs index d5bff3c..6fef477 100644 --- a/index.bs +++ b/index.bs @@ -183,6 +183,11 @@ Alternatively, you can collect a set of [Architectural Decision Records](https:/ but we don't have enough experience to recommend this structure in particular. If you have a directory of ADRs, link them from this section of your explainer. +Occasionally, an alternative will be clearly unacceptable for some reason, +for example because it's strictly worse than another alternative that is analyzed in detail in another section. +In that case, if you're sure the reviewers will agree, +you can skip the sub-sections and describe just the reason for rejection. + ## Connect to History ## {#history} Many important end-user problems have a history of failed and incomplete attempts to solve them. From d608432a24c3556557f5869935dab21da24141b1 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 29 Apr 2026 16:32:12 -0700 Subject: [PATCH 4/4] Pros/cons->advantages/disadvantages --- index.bs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 6fef477..d66162b 100644 --- a/index.bs +++ b/index.bs @@ -165,17 +165,17 @@ First, you can structure the alternative as: Explanation of the alternative design. -#### Pros +#### Advantages * List -#### Cons +#### Disadvantages * List #### Reason for rejection -Why do you feel the cons outweigh the pros? +Why do you feel the disadvantages outweigh the advantages? ``` Alternatively, you can collect a set of [Architectural Decision Records](https://adr.github.io/) as files in your repository.