diff --git a/index.bs b/index.bs index 355517b..d66162b 100644 --- a/index.bs +++ b/index.bs @@ -152,7 +152,41 @@ 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. + +#### Advantages + +* List + +#### Disadvantages + +* List + +#### Reason for rejection + +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. +[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. + +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} diff --git a/template.md b/template.md index a9364bd..4049e68 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 cons outweigh the pros?] ### [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.]