fix grammar/spelling nits (and clarify a few semantic ambiguities)

text/0005-architecture-reviews.md

@@ -4,7 +4,7 @@
 
 Architectural Review decisions within the Firefox organization fall into two categories: "Roadmap" and “Design”.
 
-Product Reviews are not the scope of this process. This process is about architectural change, which should ultimately be in support of product features, but will generally have an effect on multiple product features. Architectural change can be growing new skills or in reducing large-scale technical debt.
+Product Reviews are not within the scope of this process. This process is about architectural change, which should ultimately be in support of product features, but will generally have an effect on multiple product features. Architectural change can be growing new skills or in reducing large-scale technical debt.
 
 The function of a **Roadmap Review** is to decide if a thing should be done. The goal is to bring together a packet of data to inform a management decision to provide resources to make the thing happen. A Roadmap Review should happen early in the process so that build time isn’t wasted on a "No" decision, but so that enough information is available to management.
 
@@ -16,19 +16,19 @@ For both a Roadmap Review and a Design Review the **timetable** is as follows:
 
 1. Lay the stage. The team should document (See "initial meeting" below):
   * Someone to **chair** the review
-    - For a Roadmap Review this will be the *least* senior manager with the ability to address the problem in it's entirety.
+    - For a Roadmap Review this will be the *least* senior manager with the ability to address the problem in its entirety.
     - For a Design Review this will be the an experienced engineer in the problem domain outside of the team willing to put time into the problem. As engineers don’t review their own code they shouldn’t review their own designs.
   * The **question** (or questions) to be resolved, which should be agreed between the team asking for review and the chair.
 
 2. The team produces a **Review Packet** designed to answer the question identified in step 1. The production of the Review Packet is expected to be collaborative and iterative to ensure that the review focuses on the key questions and the team presents its best case. This is particularly true of a Roadmap Review where the consequences of the answer are likely to be more significant.
 The Review Packet includes:
   * A lay summary of the problem space and the stakeholders which is focused on defining a shared language and identifying the key forces behind the problem
-  * A brief explaining what the team proposes. This should read more like an encyclopedia entry than a marketing document. The audience is the people in the review; i.e. this should attempt to plug organizational documentation flaws, the documentation process should not be more onerous than is required for the review. The brief should identify:
+  * A brief that explains what the team is proposing. This should read more like an encyclopedia entry than a marketing document. The audience is the people in the review; i.e. this should attempt to plug organizational documentation holes. The documentation process should not be more onerous than is required for the review. The brief should identify:
     - the forces on the system
     - the essential architecture behind the proposal
     - scenarios that exercise the relevant forces against the proposed architecture
     - how the proposal handles these scenarios
-  * A competitive analysis suggesting alternatives, costs, and opportunities.
+  * A competitive analysis suggesting alternatives, costs, and opportunities
 
 3. The chair creates a list of questions to be discussed during the review. These questions should be:
   * Open-ended
@@ -37,11 +37,11 @@ The Review Packet includes:
 4. The chair convenes a review meeting. The discussions of this meeting should be carefully minuted. The meeting comprises:
   * The team making the proposal
   * The chair
-  * Other senior engineers who will provide valuable input.
+  * Other senior engineers who will provide valuable input
 
 The review meeting should be a discussion of the issues, but should avoid feeling pressured to make a decision. The goal is to understand the issues raised by the question(s) and the background from the review packet, and to add to it wisdom from the people at the review. The meeting may decide to alter the questions and undergo a subsequent review. We should be very open about conversations that happen after the review meeting.
 
-The ideal review process scales well. The same basic system should work for a quick 2 person decision over the best way to design a certain feature, and for a critical organization wide decision about a path to take. The term “team” is used above although we strongly recommend design reviews for smaller questions. If you feel yourself wondering if some design is best, it should be easy to valuable to perform a review.
+The ideal review process scales well. The same basic system should work for a quick 2 person decision over the best way to design a certain feature, and for a critical organization-wide decision about a path to take. The term “team” is used above although we strongly recommend design reviews for smaller questions. If you feel yourself wondering if some design is best, it should be easy to perform a review.
 
 For both a Roadmap Review and a Design Review the goal is to hear perspectives that will lead to a better definition of a problem or solution, and better judgment about whether it should be solved or how to solve it.
 
@@ -90,7 +90,7 @@ The second two considerations shape how the review process actually happens.
 
 The chair and the team frame the question or questions at the start of the process to ensure agreement on what should be tested. The chair is accountable for answering the question or questions following the review process.
 
-In order to agree on the question(s), the chair and the team/technical lead or principles will generally have an initial meeting. This meeting should be as small possible and is intended to:
+In order to agree on the question(s), the chair and the team/technical lead or principals will generally have an initial meeting. This meeting should be as small as possible and is intended to:
 
 * Establish vocabulary
 * Help the team "argue the right level" for the review
@@ -106,9 +106,9 @@ The chair then evaluates and refines the team’s document with the assistance o
 
 Involving the team and the chair informally and subsequently sharing ownership of a document is designed to seed a collaborative process. A particular benefit is avoiding drift between the proposal and the focus of the review.
 
-An Architecture Review process can be formally mandated. This may work in environments with a large degree of formallity and process. This isn't how Mozilla works. For an Architecture Review process to be successful at Mozilla it must be beneficial to the team undergoing review.
+An Architecture Review process can be formally mandated. This may work in environments with a large degree of formality and process. This isn't how Mozilla works. For an Architecture Review process to be successful at Mozilla it must be beneficial to the team undergoing review.
 
-The primary informal output of a review should be learning. It is exepcted that authoritarian go/no-go decisions will fall out additional learning rather than being imposed in the form of a question.
+The primary informal output of a review should be learning. It is expected that authoritarian go/no-go decisions will fall out additional learning rather than being imposed in the form of a question.
 
 ### Maturity and Dissemination
 
@@ -116,14 +116,14 @@ The final two considerations shape what is reviewed and how the review concludes
 
 A project under review will be in one of the following states:
 
-* The "Roadmap" stage: the team has a proposal, and wants broader buy-in to justify investment in the problem space.
-* The "Design" stage: the problem space is considered valuable, and the team wants to commit to one path through the solution space.
-* The "Execution" stage: the team is actively pursuing a solution.
-* The "Landing" stage: the team is verifying the solution meets expectations.
+* The "Roadmap" stage: the team has a proposal, and wants broader buy-in to justify investment in the problem space
+* The "Design" stage: the problem space is considered valuable, and the team wants to commit to one path through the solution space
+* The "Execution" stage: the team is actively pursuing a solution
+* The "Landing" stage: the team is verifying the solution meets expectations
 
 Generally our review process focuses on projects in the “Roadmap” or “Design” stages. However a project in the “Execution” or “Landing” stage may need subsequent review to decide if the project is being done the correct way, or if it should be continued at all, so it may return to either of the “Roadmap” or “Design” phases.
 
-After the review, the chair and responsible decision makers should provide concrete recommendations and examples for the next teams to undergo the review process. The results should be disseminated as widely as possible, with the package documents and recommendation document archived. Some version of the decision should be publicly linked, so that it can be the decision of record, to which blog posts, mailing list posts, the message saying that the GitHub repository is obsolete, etc, can refer. The goal is to avoid critical technical and resourcing decisions being internally settled and only — later, begrudgingly — being made public on some mailing list. Or, per RACI, the goal is to broaden the set of those Informed.
+After the review, the chair and responsible decision makers should provide concrete recommendations and examples for the next teams to undergo the review process. The results should be disseminated as widely as possible, with the package documents and recommendation document archived. Some version of the decision should be publicly linked, so that it can be the decision of record, to which blog posts, mailing list posts, the message saying that the GitHub repository is obsolete, etc., can refer. The goal is to avoid critical technical and resourcing decisions being internally settled and only — later, begrudgingly — being made public on some mailing list. Or, per RACI, the goal is to broaden the set of those Informed.
 
 ## Additional Reading
 
@@ -158,6 +158,6 @@ Jason Baragry reviews approaches to architecture review and notes some potential
 
 Formal process with input from a number of companies which targets a more enterprise environment than exists at Mozilla, however the process is clearly defined.
 
-> A software architecture is a set of concepts and design decisions about structure and texture of software that must be made prior to concurrent engineering (i.e., implementation) to enable effective satisfaction of architecturally significant, explicit functional and quality requirements, along with implicit requirements of the problem and the solution domains
+> A software architecture is a set of concepts and design decisions about structure and texture of software that must be made prior to concurrent engineering (i.e., implementation) to enable effective satisfaction of architecturally significant, explicit functional and quality requirements, along with implicit requirements of the problem and the solution domains.
 
 * https://pkruchten.files.wordpress.com/2011/09/sarav1.pdf