fix up links

fix up links

Solution_Proposal_Template.md

@@ -0,0 +1,76 @@
+[[TOC]]
+
+# Problem Statement
+
+Clearly state the problem you’re seeking to solve. This is the most difficult and most important part of the template: the problem must capture both the root technical or process concern *and* the reason why that matters. If this Problem Statement is just another way of stating the Solution Proposal, it needs to go deeper.
+
+For example, "Inter-service traffic is unencrypted" is not an effective problem statement. It doesn’t explain why this problem matters, doesn’t explain what we’re actually seeking to solve (is it confidentiality of data? Integrity of data? Authentication?), and clearly implies a solution: encrypt the traffic.
+
+Even in a crappy case where we must solve a problem because we promised auditors or clients we would solve that problem, *that is part of the problem statement*.
+
+If you’re struggling to find the right balance for expressing a problem statement, consider working with your manager to find a way to express why they should care about the problem. The [5 Whys Technique](https://en.wikipedia.org/wiki/5_Whys) is also a useful model.
+
+# Proposed Solution
+
+## Summary
+
+Explain the solution. This does not need to be a full-fledged design but it needs to be concrete and thought-through enough to evaluate how it solves the problem. Questions to consider as you write this section:
+
+* What details would a reader need to know to plan a similar implementation?
+
+* How does this solve the original problem statement?
+
+* Can this solution be simplified?
+
+* Does this solution have an expiration date or hard scaling ceiling?
+
+* Does this solution introduce new technology where existing technology might do?
+
+* How will this solution be managed and maintained by a team?
+
+## Constraints
+
+What assumptions guided you while formulating this solution? For example, many current infrastructure projects must be designed under the constraint that SM exists as a hybrid private/public cloud for the next couple years.
+
+This section should both preemptively answer many "Why didn’t you ____?" questions and help future readers contextualize decisions made in the past.
+
+# Alternative: [A]
+
+## Summary
+
+Offer a briefer summary of this alternative solution. This does not need to be in the same detail as your proposal, but does need to be sufficiently fleshed out to ensure readers are on the same page with you when discussing options.
+
+## How is this alternative superior?
+
+How is this alternative better than the main proposal? The goal of this section is to fully represent why someone might prefer this idea to ensure that this document is grounded in solving the problem rather than advocating for a technical idea.
+
+This should be persuasive. If you find yourself tempted to swap the proposal with this alternative, you’re doing it right. If you *do* swap, even better.
+
+## Why choose against this alternative?
+
+Why did you choose to go with the main proposal over this alternative? This should be an accounting of your reasoning rather than just a list of cons. What were the most significant factors in your decision?
+
+Again, this should be persuasive. Even if your audience disagrees with your choice, they should come away from this section understanding and respecting exactly why you made it.
+
+# Alternative: [B]
+
+## Summary
+
+Offer a briefer summary of this alternative solution. This does not need to be in the same detail as your proposal, but does need to be sufficiently fleshed out to ensure readers are on the same page with you when discussing options.
+
+## How is this alternative superior?
+
+How is this alternative better than the main proposal? The goal of this section is to fully represent why someone might prefer this idea to ensure that this document is grounded in solving the problem rather than advocating for a technical idea.
+
+This should be persuasive. If you find yourself tempted to swap the proposal with this alternative, you’re doing it right. If you *do* swap, even better.
+
+## Why choose against this alternative?
+
+Why did you choose to go with the main proposal over this alternative? This should be an accounting of your reasoning rather than just a list of cons. What were the most significant factors in your decision?
+
+Again, this should be persuasive. Even if your audience disagrees with your choice, they should come away from this section understanding and respecting exactly why you made it.
+
+# Alternative: [...]
+
+Flesh out at least two diligently researched alternatives. If there are others that were strongly considered, that you expect to come up in conversations about this solution, or that help flesh out your decision-making process, add them here.
+

Technical Design Process.md

@@ -7,7 +7,7 @@ This work is licensed under the Creative Commons Attribution 4.0 License (CC-BY-
 
 # The problem
 
-As discussed in [Appendix A](#heading=h.88sxb7lelwsv), there are two broad categories of technical implementation: organic, evolved change and designed change. To scale as a company, we must move from a predominantly organic approach to a designed approach.
+As discussed in Appendix A, there are two broad categories of technical implementation: organic, evolved change and designed change. To scale as a company, we must move from a predominantly organic approach to a designed approach.
 
 Traditional design processes usually review only after completion of the full, detailed technical design document. This typically renders the review process moot since so much work has already been sunk into the project and, often, an actual implementation was built alongside the document itself. 
 
@@ -116,7 +116,7 @@ Finally, there will be times when the *why *is arbitrary: if PCI compliance dema
 
 The hardest part of expressing the *what* of a problem is knowing *which* problem to solve. This is a critical judgement call.
 
-One effective approach is to list a handful of candidates and then break down the assumptions behind each of them. Running systems are messy, especially when distributed, so the best problem to solve will typically have few optimistic assumptions about the world. The optimizations in [Appendix B](#heading=h.v4mmh7sjtcry) may also be helpful reality checks.
+One effective approach is to list a handful of candidates and then break down the assumptions behind each of them. Running systems are messy, especially when distributed, so the best problem to solve will typically have few optimistic assumptions about the world. The optimizations in Appendix B may also be helpful reality checks.
 
 For example, consider a site outage caused by loss of the link between our US and EU datacenters after a submarine volcano erupts and severs a primary trans-Atlantic fiber link. Which problem needs to be solved?
 
@@ -138,9 +138,9 @@ If you’re unable to separate the problem from your proposed solution, consider
 
 ## II. Solution Proposal document
 
-**_Deliverable: _***a completed proposal based on the **[Solution Proposal Templat*e](https://docs.google.com/document/d/1P8upq4Y0kstBXwKl0lBmL_g49ciouQkbJMu-VNVIXrs/edit?usp=sharing)*.*
+**_Deliverable: _***a completed proposal based on the [Solution Proposal Template](Solution_Proposal_Template.md)*.*
 
-Complete a Solution Proposal from the [Solution Proposal Template](https://docs.google.com/document/d/1P8upq4Y0kstBXwKl0lBmL_g49ciouQkbJMu-VNVIXrs/edit?usp=sharing), using your finished Problem Statement for the first section. The template is self-explanatory, but in broad strokes its sections are:
+Complete a Solution Proposal from the [Solution Proposal Template](Solution_Proposal_Template.md), using your finished Problem Statement for the first section. The template is self-explanatory, but in broad strokes its sections are:
 
 * **Problem Statement. **You’ve already finished this.
 
@@ -426,11 +426,11 @@ Continue cycling until you reach a break-point appropriate for review. Review sh
 
 #### Review
 
-Let your panel know where you’re at in the TDD and schedule a review. This review follows roughly the same process as [review of the Proposal](#heading=h.vt175wltekjb). Once again, the intent is to help the Designer make the very best possible decisions.
+Let your panel know where you’re at in the TDD and schedule a review. This review follows roughly the same process as review of the Proposal. Once again, the intent is to help the Designer make the very best possible decisions.
 
 Focus on missing details, structure, and broad issues with serious runtime implications. This review process is not a venue for bikeshedding; it exists to make sure the implementation works, accounts for operationalization and runtime questions, doesn’t paint future generations into a corner, and so on.
 
-[There’s always an exit hatch](#heading=h.bgmlf1z8064l), but the use of Solution Proposals ought to cull out most non-starters. While vetoes should be exceedingly rare at this stage, the process is the same.
+There’s always an exit hatch, but the use of Solution Proposals ought to cull out most non-starters. While vetoes should be exceedingly rare at this stage, the process is the same.
 
 #### Repeat
 
@@ -440,7 +440,7 @@ Some projects will require only a single TDD review while others may require man
 
 ### When to revisit the Solution Proposal
 
-If you realize the proposal you chose is not doable, [return to that step](#heading=h.o1csimhqfnc). Move the current solution to an alternative and mark it as rejected with a link to the TDD and an explanation of the blockers you ran into.
+If you realize the proposal you chose is not doable, return to that step. Move the current solution to an alternative and mark it as rejected with a link to the TDD and an explanation of the blockers you ran into.
 
 Do not throw good money after bad; the Solution Proposal is a lightweight document that is intended to catch rather coarse problems. There will inevitably be accepted Proposals that must be abandoned because subtler issues were discovered in the TDD step. **This is not a bad thing--they were still caught before moving to implementation.**
 
@@ -476,7 +476,7 @@ Alternatives play an important role keeping the solution proposal honest, comple
 
 If you’re faced with a set of equally crappy options, these strategies might help:
 
-* **Search for more alternatives.** Use [the above strategies](#heading=h.tuchcqi7moop) until you’re confident that you’ve got the best set of alternatives available to you.
+* **Search for more alternatives.** Use the above strategies until you’re confident that you’ve got the best set of alternatives available to you.
 
 * **Discuss with someone you trust.** Fresh eyes might see something you don’t.