Linked up the new chapter

Author: mcasperson

_includes/abstractions.html renamed to _includes/choosing_responsibility.html

@@ -1,4 +1,4 @@
-<h1><a id="abstractions">The "abstractions with infinite flexibility" fallacy</a></h1>
+<h1><a id="choosing_responsibility">Choosing a responsibility model</a></h1>
 
 <p>Those looking to introduce platform engineering into existing DevOps teams face three common realities:</p>
 
@@ -46,7 +46,7 @@ <h1><a id="abstractions">The "abstractions with infinite flexibility" fallacy</a
 
 <p>
     The only safe initial answer to this question is "No", with an aim to reach the point where the answer is "Yes, but...".
-    You will never have perfect knowledge of your customer's needs, but a successful platform team can refine their
+    While you will never have perfect knowledge of your customer's needs, a successful platform team can refine their
     abstractions over time. But you do need to have some level of early success to earn the time required to refine
     your solutions.
 </p>
@@ -55,43 +55,65 @@ <h1><a id="abstractions">The "abstractions with infinite flexibility" fallacy</a
     Anyone aiming to provide an opinionated solution faces this same dilemma, but the survivorship bias of every
     successful abstraction you see in daily life can make it seem like building abstractions is easy. However, new
     platform teams must assume building abstractions is, in fact, quite difficult, and therefor have a plan to support
-    customers with unique needs or opinions of their own. This is the crux of the responsibility levels presented in
+    customers with unique needs or opinions of their own. This is the crux of the responsibilities presented in
     the chapter "Platform Engineering Responsibility Models":
 </p>
 
 <ul>
     <li>
-        Centralized responsibility artifacts provide highly opinionated solutions exposing a relatively small number of
+        Centralized responsibility (or "enforced consistency") artifacts provide highly opinionated solutions exposing a relatively small number of
         options to customize the end result. These artifacts favor enforcing opinions over allowing flexibility. The
         success of the centralized responsibility model is highly dependent on how closely aligned your abstractions are
         to the needs of your customers.
     </li>
     <li>
-        Shared responsibility artifacts can be modified by customers, providing them with the ability to customize their
+        Shared responsibility (or "eventual consistency") artifacts can be modified by customers, providing them with the ability to customize their
         solution while still allowing the platform team to centrally distribute updates. These artifacts are the most
         flexible and provide a sliding scale between enforcing opinions and exposing flexibility (with the caveat that increased
         customization will typically decrease the ability to centrally distribute updates). The shared responsibility
         model assumes abstractions will be imperfect and emphasises a workflow that allows platform teams and their
         customers to jointly refine the solution over time.
     </li>
     <li>
-        Customer responsibility artifacts provide customers with a base template that they are expected to own and
+        Customer responsibility (or "eventual inconsistency") artifacts provide customers with a base template that they are expected to own and
         modify to suit their needs. While the templates can provide an initial set of opinions, they are
         expected to be heavily modified. The customer responsibility model assumes customers will keep what is useful
         and discard what is not.
     </li>
 </ul>
 
 <p>
-    An anti-pattern to avoid when starting a new platform team is focusing to heavily on the centralized responsibility model. This
+    An anti-pattern to avoid when starting a new platform team is focusing too heavily on the centralized responsibility model. This
     model requires that you build the most accurate abstractions, and starting a new platform team is the time when you
-    have the least amount of information.
+    have the least amount of information to do so.
 </p>
 
 <p>
-    The shared responsibility model requires platform teams to build workflows that facilitate shared development of
-    artifacts. While tools like Git provide a great foundation for these workflows, platform teams must still invest
-    time in ensuring artifacts can be tracked and merged over time. The benefit of this model is that it provides a
-    direct feedback loop between the platform team and your customers and accepts that the abstractions underpinning
-    your IDPs artifacts will need to evolve over time.
-</p>
+    Instead, new platform teams should aim to initially offer artifacts under the shared responsibility or customer responsibility models.
+    In the unlikely event that you managed to get your abstractions just right first time, there is little practical
+    difference between the three responsibility models, as the resulting solutions will all remain mostly unchanged
+    from the initial artifact generated by your IDP. However, in the more likely event that your abstractions require
+    refinement, the shared responsibility model allows you to work with your customers to evolve your abstractions, and
+    the customer responsibility model allows customers to make whatever changes they need.
+</p>
+
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
+<p><i>
+    I was part of a team that designed new steps in Octopus to deploy applications to Kubernetes and AWS ECS. One of the
+    challenges in designing these steps was deciding how to support use cases we hadn't anticipated or might be introduced
+    by the underlying platforms after our steps were released. After spending some time thinking about all the hooks or
+    custom scripting we could expose in these steps, we decided that the best course of action was to offer both
+    highly opinionated steps that supported most common use cases and generic steps that allowed the deployment of
+    raw YAML for either Kubernetes resources or CloudFormation templates. Importantly, the opinionated steps offered a way
+    to export the equivalent YAML that they would generate, giving customers a way to jump from the opinionated step
+    (which aligns with the central responsibility model) to the generic step (which aligns with the customer
+    responsibility model).
+</i></p>
+
+<p><i>
+    This kind of "break glass in emergency" process to move from one responsibility model to another meant we could
+    offer a path for any customers blocked by a lack of functionality in the opinionated steps, with the understanding
+    that customers had to take more responsibility for what was now considered bespoke YAML. This is a practical, and
+    now battle tested, example of the responsibility models in action.
+</i></p>

_includes/responsibility.html

@@ -48,6 +48,11 @@ <h2>Customer Responsibility</h2>
     structure, is an ideal candidate for the customer responsibility model, as customers will drastically alter this
     project template almost immediately.</p>
 
+<p>
+    The customer responsibility model can be thought of as an "eventual inconsistency" model where teams start with
+    the same foundation by diverge as they customize their solution.
+</p>
+
 <div><img alt="DevOps Lifecycle" src="images/customer-responsibility-model.png"/></div>
 
 <h2>Shared Responsibility</h2>
@@ -79,6 +84,11 @@ <h2>Shared Responsibility</h2>
     Customers may be happy to pull in changes as required, or the platform team may need to do the work to push changes
     out.</p>
 
+<p>
+    The shared responsibility model represents an "eventual consistency" model where the platform team and their customers
+    work in parallel and eventually merge any useful changes.
+</p>
+
 <div><img alt="DevOps Lifecycle" src="images/shared-responsibility-model.png"/></div>
 
 <h2>Centralized Responsibility</h2>
@@ -116,6 +126,11 @@ <h2>Centralized Responsibility</h2>
 <p>As your IDP gains traction, your customer's requirements will test the bounds of complex artifacts distributed under
     the centralized responsibility model.</p>
 
+<p>
+    The centralized responsibility model is an "enforced consistency" model where the platform team retains most of the
+    control of any artifacts generated by the IDP.
+</p>
+
 <div><img alt="DevOps Lifecycle" src="images/central-responsibility-model.png"/></div>
 
 <h2>Customization as Feedback</h2>

book.html

@@ -15,6 +15,7 @@
     {% include pe_value.html %}
     {% include planning.html %}
     {% include responsibility.html %}
+    {% include choosing_responsibility.html %}
     {% include tenpillars.html %}
     {% include epilouge.html %}
 </body>