apply review suggestions

cosmos · Jun 28, 2023 · d976bdc · d976bdc
1 parent f2d3522
commit d976bdc
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 6 deletions.
diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md
@@ -1,8 +1,8 @@
 # ADR Creation Process
 
 1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md`
-2. Create a draft Pull Request if you want to get an early feedback.
-3. Make sure the context and a solution is clear and well documented.
+2. Create a draft Pull Request and solicit input from the stewarding team, if you want to get an early feedback.
+3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded.
 4. Add an entry to a list in the README file [Table of Contents](./README.md#adr-table-of-contents).
 5. Create a Pull Request to propose a new ADR.
 
@@ -18,9 +18,9 @@ ADR creation is an **iterative** process. Instead of trying to solve all decisio
 
 4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue.
 
-5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to  merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it.
+5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it.
 
-6. Merged ADRs SHOULD NOT be pruned.
+6. Merged ADRs SHOULD NOT be deleted.
 
 ### ADR status
 

diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -13,7 +13,7 @@ An Architectural Decision (**AD**) is a software design choice that addresses a
 An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality.
 An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM).
 
-You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t).
+You can read more about the ADR concept [here](https://adr.github.io/).
 
 ## Rationale
 
@@ -23,6 +23,7 @@ An ADR should provide:
 - Context on the relevant goals and the current state
 - Proposed changes to achieve the goals
 - Summary of pros and cons
+- Discarded solution spaces and why they were discarded
 - References
 - Changelog
 
@@ -31,7 +32,7 @@ justification for a change in architecture, or for the architecture of something
 new. The spec is much more compressed and streamlined summary of everything as
 it stands today.
 
-If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.
+If recorded decisions turn out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.
 
 ## Creating new ADR