:wq

wq
Merge branch 'main' of https://github.com/OctopusSolutionsEngineering/PlatformEngineeringBook

Author: mcasperson

Platform Engineering for Dummies.edited.odt

@@ -0,0 +1,11 @@
+<h1><a id="conventions">Conventions</a></h1>
+
+<p>This book shares many real life anecdotes to help illustrate a point or provide additional context.</p>
+
+<p>These anecdotes are indicated by the following icons, and written in italics:</p>
+
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
+<p>
+    <i>This is a real life story or example that relates to the main text.</i>
+</p>

_includes/conventions.html

@@ -48,7 +48,7 @@ <h2>Platform Engineering by the Numbers</h2>
     hours on undifferentiated efforts weekly, or roughly 10% to 20% of their week on things that are not related to
     building new products. Another survey found that engineers spend 30% of their time on "repetitive tasks."</p>
 
-<p>The article goes on to list the six tenants used by the ASBX team:</p>
+<p>The article goes on to list the six tenets used by the ASBX team:</p>
 
 <ol>
     <li>Software builders across Amazon require consistent, interoperable, and extensible tools to construct and operate
@@ -130,22 +130,20 @@ <h2>Quantifying the Business Value</h2>
     increases. It is harder to show independent increases to shareholder value, but it is included here for
     completeness.</p>
 
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
 <p><i>Emma Maslen, the author of the post above, included shareholder value to capture cases where businesses were
     working towards efforts like environmental initiatives or diversity, equity and inclusivity that may not necessarily
     impact risk, cost, or revenue. In most cases, shareholder value is a consequence of changes to the other three pain
     points.</i></p>
 
-<p>The chapter “Planning your Internal Developer Platform” notes that a clear mission and focus are vital to a
-    successful IDP implementation. The mission statement is also an opportunity to address one or more of these four
-    pain points.</p>
-
 <p>Fortunately, an IDP has plenty of scope to impact business value positively. By infusing best practices at scale
     throughout your DevOps teams, it is reasonable to argue that your IDP directly reduces friction, improves DevEx,
     improves deployment frequency, or improves compliance. Importantly, these improvements are repeatable and scalable.
     The final step is to describe these improvements in terms of business concerns like risk, cost, or revenue.</p>
 
-<p>Unlike the mission statement, the business value captured in this process must be expressed as a number to ensure it
-    is measurable. Defining measurable values involves answering questions like:</p>
+<p>The business value of a platform team must be expressed as a number to ensure it is measurable. Defining measurable
+    values involves answering questions like:</p>
 
 <ul>
     <li>How much money will be earned from new features delivered as a result of the increased performance of DevOps

_includes/pe_value.html

@@ -22,51 +22,50 @@ <h2>What is DevOps Not?</h2>
             href="https://oc.to/r2TWX0">https://oc.to/r2TWX0</a>), where generative cultures high
     in trust and low in blame exhibit higher performance.</p>
 
-<p>These definitions show us that the processes and cultural foundations that support and improve the delivery of
-    features, reduce defects, and reduce the time to resolve issues are all the responsibility of DevOps teams.</p>
+<p>So the DevOps lifecycle makes DevOps teams responsible for tooling and processes, Westrum's organizational
+    cultures makes them responsible for all human interactions, and the DORA metrics makes them responsible for all
+    measurable outcomes.</p>
 
-<p>And these are just two of the more popular interpretations of DevOps. One of the great successes of the DevOps
+<p>And these are just three of the more popular perspectives on DevOps. One of the great successes of the DevOps
     movement is that it encourages new perspectives on the metrics, processes, ideals, and cultural underpinnings of the
     field.</p>
 
-<p>But even with just the DevOps lifecycle, DORA metrics, and Westrum organizational culture, we can attempt to answer
+<p>But even with just the DevOps lifecycle, DORA metrics, and Westrum's organizational culture, we can attempt to answer
     the question “What is DevOps not?”</p>
 
-<p>There is no satisfying answer to that question. The term DevOps has become almost unfalsifiable, but this is quite by
+<p>There is no satisfying answer to that question.</p>
+
+<p>The term DevOps has become almost unfalsifiable, but this is quite by
     design. DevOps has unashamedly sought to break down silos and absorb responsibilities that previously separated
-    teams
-    creating and delivering technical solutions, while simultaneously building a culture of psychological safety to
-    encourage creative problem solving. The ideal DevOps team is self-sufficient, with the ability,
-    willingness, confidence, and responsibility to tackle any and every problem.</p>
+    teams creating and delivering technical solutions, while simultaneously building a culture of psychological safety
+    to encourage creative problem-solving. The ideal DevOps team is self-sufficient, with the ability, willingness,
+    confidence, and responsibility to tackle any and every problem.</p>
 
 <p>But for every ideal DevOps team thriving on the responsibility of owning their own destiny, there is another team
-    slowly
-    drowning under the constant need to resolve every brittle process and incorporate every new responsibility
-    encountered in the DevOps lifecycle. The mental
-    burden of this undifferentiated and unsatisfying work has come to define their existence, leading to a downward
-    spiral of dispirited and low performing teams. Or, put more simply, teams with an unsatisfactory developer
-    experience.</p>
+    slowly drowning under the constant need to resolve every brittle process and incorporate every new responsibility
+    encountered in the DevOps lifecycle. The mental burden of this undifferentiated and unsatisfying work has come to
+    define their existence, leading to a downward spiral of dispirited and low performing teams. Or, put more simply,
+    teams with an unsatisfactory developer experience.</p>
+
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
 
 <p><i>
     I found myself working as a developer on a codebase whose test suite would fail far more often than it passed. A few
-    manual retries
-    would solve the issue and ensure that pull requests could progress, although retrying the tests could take days.
+    manual retries would solve the issue and ensure that pull requests could progress, although retrying the tests could
+    take days.
 </i></p>
 
 <p><i>
     The suggestion proposed by the engineering leadership at the time was that everyone should stop what they were doing
-    and fix the
-    tests. This is typically sound advice and very much in line with practices like Test Driven Design (TDD).
-    Unfortunately, every developer
-    on the team intrinsically understood that fixing the tests was a dedicated project it its own right. There were no
-    quick wins.
+    and fix the tests. This is typically sound advice and very much in line with practices like Test Driven Design
+    (TDD). Unfortunately, every developer on the team intrinsically understood that fixing the tests was a dedicated
+    project it its own right. There were no quick wins.
 </i></p>
 
 <p><i>
     This forced everyone to quietly calculate the tradeoffs between wasting days on test retries and devoting weeks to
-    undertaking
-    the unplanned work of fixing the tests. Needless to say, we ended up wasting a lot of time clicking that retry
-    button.
+    undertaking the unplanned work of fixing the tests. Needless to say, we ended up wasting a lot of time clicking that
+    retry button.
 </i>
 </p>
 
@@ -130,7 +129,9 @@ <h2>What is Platform Engineering?</h2>
 </ul>
 
 <p>It is easy to see that common solutions to common requirements are the only sustainable path for growing
-    DevOps teams.
+    DevOps teams. While the unfalsifiability of the responsibilities assigned to DevOps teams is still a concern, common
+    solutions to common requirements do reduce the scope of those responsibilities that DevOps teams must
+    actively focus on.
 </p>
 
 <p>In our hypothetical scenario, the obvious solution is to deploy a CI server. But CI servers had to start somewhere.
@@ -146,10 +147,9 @@ <h2>What is Platform Engineering?</h2>
 <p>Thus a common solution to a common requirement was born. It is also no coincidence that Jenkins was born to improve
     Kohsuke's DevEx.</p>
 
-<p>While CI servers are a solved problem (at least from the point
-    of most DevOps team), environments with multiple DevOps teams working side by side will no doubt
-    have many more common requirements. Addressing these common requirements with artifacts generated by your IDP
-    is the goal of a platform team.
+<p>While CI servers are a solved problem (at least for most DevOps teams), environments with multiple DevOps teams
+    working side by side will no doubt have many more common requirements. Addressing these common requirements with
+    artifacts generated by your IDP is the goal of a platform team.
 </p>
 <p>
     Common artifacts generated by an IDP include:
@@ -168,7 +168,7 @@ <h2>What is Platform Engineering?</h2>
 <h2>Conclusion</h2>
 
 <p>DevOps is arguably the best philosophy we have to build high performing teams to deliver technical solutions. But
-    while DevOps can be used as the foundation for great teams, the demands placed on teams must be matched
+    while DevOps can be used as the foundation for great teams, the demands placed on them must be matched
     by their capability. Asking DevOps teams to provide their own unique implementation to every requirement leads to
     inconsistent solutions at best and eventually creates an unsustainable environment. This in turn leads to
     frustration and poor DevEx.</p>

_includes/pe_vs_devops.html

@@ -112,6 +112,8 @@ <h2>User Interviews</h2>
 <p class="quote">It has to solve a need, it has to be compelling, and you need to treat it like a
     product.</p>
 
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
 <p><i>For those from an engineering background, talking to customers can elicit a feeling of dread. As an engineer, I
     never wanted to talk to customers because every customer I ever interacted with asked me to fix a bug or solve a
     problem. This order-taking was tolerable via asynchronous communication like email, but face-to-face conversation
@@ -163,6 +165,8 @@ <h2>Documentation and Training</h2>
     understand and implement the solution without requiring a personal demonstration every time. Documentation and
     training are two proven solutions for upskilling customers at a time and pace that suits them.</p>
 
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
 <p><i>"Any product that needs a manual to work is broken." It's a catchy quote from Elon Musk, and yet the first time I
     caught a Tesla Model 3, my Uber driver had to open the door for me because I didn't know how the handles worked.
     Thankfully, and ironically, Tesla's online owner's manual has excellent documentation on how to open the doors. I'll
@@ -211,6 +215,8 @@ <h2>Issue Tracking and Feature Requests</h2>
     will likely have an issue tracker already in use by your DevOps teams, and reusing it for your IDP is a natural
     choice.</p>
 
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
 <p><i>Be confident enough to admit you must wait to implement new features. While working in product teams, I was
     overwhelmed with requests for new features and improvements and felt that confessing that we wouldn't consider even
     great ideas for at least 6 to 12 months was admitting defeat. Often, I just ignored these requests, but that was a
@@ -233,6 +239,8 @@ <h2>Marketing</h2>
     changes. Lunch-and-learn sessions are another excellent way to reach your internal customers. Also, consider
     recording a demonstration of the new features and sharing it as a monthly webinar.</p>
 
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
 <p><i>One of the tips I learned when I moved to a sales team was the value of existing, general-purpose meetings
     preallocated in a team’s calendar. Never underestimate how hard it is to find a time for everyone to meet. Being
     able to present at a lunch-and-learn is an incredible opportunity for your marketing efforts.</i></p>
@@ -267,6 +275,8 @@ <h2>Feedback</h2>
     rather than second hand via channels like social media, platform teams benefit from the opportunity to resolve these
     issues directly rather than hearing from the CTO that their IDP is not meeting expectations.</p>
 
+<div><img class="icon" alt="Anecdotes Icon" src="images/anecdote.png"/></div>
+
 <p><i>A common pattern I have noticed in many mobile apps is a two-step feedback process. The first question is designed
     to gauge whether the customer would provide a positive or negative rating. Those that indicated they would provide a
     negative rating are redirected to an internal feedback channel, while those providing positive feedback are

_includes/planning.html

@@ -9,6 +9,7 @@
 </head>
 
 <body>
+    {% include conventions.html %}
     {% include introduction.html %}
     {% include pe_vs_devops.html %}
     {% include pe_value.html %}

book.html

@@ -87,3 +87,10 @@ h2, h3 {
 .quote {
     margin-left: 2em;
 }
+
+.icon {
+    width: 32px;
+    height: 32px;
+    margin-left: unset;
+    margin-right: unset;
+}