Merge pull request #597 from buildpacks/ste-review

Address technical language review

docs/app-developer-guide/build-a-windows-app/index.html

@@ -704,16 +704,16 @@ <h1 class="title">Build a Windows app</h1>
         </div>
 
         <blockquote>
-<p><strong>EXPERIMENTAL</strong> Windows support is experiment!</p>
+<p><strong>EXPERIMENTAL</strong> Windows support is experimental!</p>
 <p>Enable experimental mode by running: <code>pack config experimental true</code></p>
 </blockquote>
-<h3 id="precursor">Precursor</h3>
+<h3 id="before-you-start">Before You Start</h3>
 <h4 id="recommended-reading">Recommended reading</h4>
 <p>Before trying out builds for Windows images, we recommend following the <a href="/docs/app-journey">Linux image tutorial</a> under <a href="/docs">Getting Started</a>. Don&rsquo;t worry, you can still run it on a Windows OS if you need to &ndash; just make sure to <a href="https://docs.docker.com/desktop/faqs/windowsfaqs/#how-do-i-switch-between-windows-and-linux-containers">enable Linux containers</a> for Docker first.</p>
 <p>When you&rsquo;re done, head back here.</p>
 <h4 id="enable-windows-container-mode">Enable Windows container mode</h4>
 <p>In order to produce Windows container images, ensure <a href="https://docs.docker.com/desktop/faqs/windowsfaqs/#how-do-i-switch-between-windows-and-linux-containers">Windows container mode</a> is enabled in your Docker settings (available only in Docker for Windows).</p>
-<p>Then, building a Windows app using Cloud Native Buildpacks is nearly identical to <a href="/docs/app-developer-guide/build-an-app">building for Linux</a>:</p>
+<p>Then, building a Windows app using Cloud Native Buildpacks is nearly identical to <a href="/docs/app-developer-guide/build-an-app">building for Linux</a>.</p>
 <blockquote>
 <p><strong>Not using Windows?</strong></p>
 <p><code>pack</code> can build Windows apps using a remote Windows Docker by setting a <code>DOCKER_HOST</code>. <a href="#using-remote-docker-hosts">Learn more</a></p>

docs/app-developer-guide/build-an-app/index.html

@@ -703,13 +703,7 @@
           <h1 class="title">Build an app</h1>
         </div>
 
-        <!--+- if false+-->
-<div class="quote mb-4">
-    Build is the process of executing one or more buildpacks against the app’s source code to produce a runnable OCI image.
-    <div class="author"><a href="/docs/concepts/operations/build">build</a></div>
-</div>
-<!--+- end+-->
-<!--+- `
+        <!--+- `
 # Build an app
 `+-->
 <p>Building an app using Cloud Native Buildpacks is as easy as <code>1</code>, <code>2</code>, <code>3</code>&hellip;</p>

docs/app-journey/index.html

@@ -719,14 +719,14 @@ <h2 id="pack-for-the-journey">Pack for the journey</h2>
 <h2 id="buildpack-base-camp">Buildpack base camp</h2>
 <p>Before we set out, you&rsquo;ll need to know the basics of <strong>buildpacks</strong> and how they work.</p>
 <h3 id="what-is-a-buildpackbuildpack">What is a <a href="/docs/concepts/components/buildpack/">buildpack</a>?</h3>
-<p>A buildpack is something you&rsquo;ve probably leveraged without knowing, as they&rsquo;re currently
+<p>A buildpack is something you&rsquo;ve probably used without knowing it, as they&rsquo;re currently
 being used in many cloud platforms. A buildpack&rsquo;s job is to gather everything your app needs to build and run,
 and it often does this job quickly and quietly.</p>
 <p>That said, while buildpacks are often a behind-the-scenes detail, they are at the heart of transforming your source
 code into a runnable app image.</p>
 <h5 id="auto-detection">Auto-detection</h5>
-<p>What enables buildpacks to go unnoticed is auto-detection. This happens when a platform sequentially
-tests groups of buildpacks against your app&rsquo;s source code. The first group that deems itself fit for your source code
+<p>What enables buildpacks to be transparent is auto-detection. This happens when a platform sequentially
+tests groups of buildpacks against your app&rsquo;s source code. The first group that successfully detects your source code
 will become the selected set of buildpacks for your app. Detection criteria is specific to each buildpack &ndash; for
 instance, an <strong>NPM buildpack</strong> might look for a <code>package.json</code>, and a <strong>Go buildpack</strong> might look for Go source files.</p>
 <h3 id="what-is-a-builderbuilder">What is a <a href="/docs/concepts/components/builder/">builder</a>?</h3>

docs/buildpack-author-guide/create-buildpack/index.html

@@ -704,8 +704,6 @@ <h1 class="title">Create a buildpack</h1>
         </div>
 
         <!--+if false+-->
-<p>You can also follow an interactive version of this guide on Katacoda.</p>
-
 <h2 id="prerequisites">Prerequisites</h2>
 <p>Before we get started, make sure you&rsquo;ve got the following installed:</p>
 <p><a href='https://store.docker.com/search?type=edition&amp;offering=community' class='download-button button icon-button bg-blue'> Install Docker </a><br />

docs/buildpack-author-guide/index.html

@@ -749,7 +749,7 @@ <h2><a href="https://buildpacks.io/docs/buildpack-author-guide/caching-strategie
             </div>
 
           <h2><a href="https://buildpacks.io/docs/buildpack-author-guide/build-phases-overview/" class="">Overview of Buildpacks Phases</a></h2>
-          <p class="m-1">We work through a full example of building a &ldquo;hello world&rdquo; NodeJs web application. In the example we run pack on the NodeJS application to produce an application image. We assume that we have a NodeJS buildpack, registry.fake/buildpacks/nodejs:latest, that is decomposed into buildpacks that help with the build. We expand each of the buildpacks phases to explain the process. Throughout the example we take a production-level view of their operation. For example, our assumed NodeJS buildpack will be described to create different build, cache and launch layers in a manner similar to how a real NodeJS buildpack would operate.</p>
+          <p class="m-1">We work through a full example of building a “hello world” NodeJs web application. In the example we run pack on the NodeJS application to produce an application image. We assume that we have a NodeJS buildpack, registry.fake/buildpacks/nodejs:latest, that is decomposed into buildpacks that help with the build. We expand each of the buildpacks phases to explain the process. Throughout the example we take a production-level view of their operation. For example, our assumed NodeJS buildpack will be described to create different build, cache and launch layers in a manner similar to how a real NodeJS buildpack would operate.</p>
 
 
             <div class="text-md-right">

docs/concepts/components/index.html

@@ -717,17 +717,15 @@ <h2><a href="https://buildpacks.io/docs/concepts/components/builder/" class="">B
             </div>
 
           <h2><a href="https://buildpacks.io/docs/concepts/components/buildpack/" class="">Buildpack</a></h2>
-          <p class="m-1"> A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.
-</p>
+          <p class="m-1">A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/concepts/components/buildpack/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/concepts/components/lifecycle/" class="">Lifecycle</a></h2>
-          <p class="m-1"> The lifecycle orchestrates buildpack execution, then assembles the resulting artifacts into a final app image.
-</p>
+          <p class="m-1">The lifecycle orchestrates buildpack execution, then assembles the resulting artifacts into a final app image.</p>
 
           <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/concepts/components/lifecycle/">Learn more →</a>
@@ -743,17 +741,19 @@ <h2><a href="https://buildpacks.io/docs/concepts/components/buildpack-group/" cl
             </div>
 
           <h2><a href="https://buildpacks.io/docs/concepts/components/platform/" class="">Platform</a></h2>
-          <p class="m-1"> A platform uses a lifecycle, buildpacks (packaged in a builder), and application source code to produce an OCI image.
-</p>
+          <p class="m-1">A <code>platform</code> uses a <a href="/docs/concepts/components/lifecycle/">lifecycle</a>, <a href="/docs/concepts/components/buildpack/">buildpacks</a> (packaged in a <a href="/docs/concepts/components/builder/">builder</a>), and application source code to produce an OCI image.</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/concepts/components/platform/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/concepts/components/stack/" class="">Stack</a></h2>
-          <p class="m-1"> A stack is composed of two images that are intended to work together:
-The build image of a stack provides the base image from which the build environment is constructed. The build environment is the containerized environment in which the lifecycle (and thereby buildpacks) are executed. The run image of a stack provides the base image from which application images are built. </p>
+          <p class="m-1"><p>A stack is composed of two images that are intended to work together:</p>
+<ol>
+<li>The <strong>build image</strong> of a stack provides the base image from which the build environment is constructed. The build environment is the containerized environment in which the <a href="/docs/concepts/components/lifecycle/">lifecycle</a> (and thereby <a href="/docs/concepts/components/buildpack/">buildpacks</a>) are executed.</li>
+<li>The <strong>run image</strong> of a stack provides the base image from which application images are built.</li>
+</ol></p>
 
 
             <div class="text-md-right">

docs/concepts/operations/index.html

@@ -717,7 +717,7 @@ <h2><a href="https://buildpacks.io/docs/concepts/operations/build/" class="">Bui
             </div>
 
           <h2><a href="https://buildpacks.io/docs/concepts/operations/rebase/" class="">Rebase</a></h2>
-          <p class="m-1">Rebase allows app developers or operators to rapidly update an app image when its stack&rsquo;s run image has changed.</p>
+          <p class="m-1">Rebase allows app developers or operators to rapidly update an app image when its stack’s run image has changed.</p>
 
 
             <div class="text-md-right">

docs/features/dockerfiles/index.html

@@ -8,7 +8,7 @@
 <meta charset="utf-8">
 <meta http-equiv="x-ua-compatible" content="ie=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
-<meta name="description" content="Dockerfiles can be used to extend base images for buildpacks builds"/>
+<meta name="description" content="Dockerfiles can be used to extend base images for buildpacks builds."/>
 <link rel="canonical" content="https://buildpacks.io/docs/features/dockerfiles/">
 <link rel="icon" type="image/png" href="/images/favicon.png">
 
@@ -22,7 +22,7 @@
 <meta property="og:url" content="https://buildpacks.io/docs/features/dockerfiles/">
 <meta property="og:locale" content="en_US">
 <meta property="og:site_name" content="Cloud Native Buildpacks">
-<meta property="og:description" content="Dockerfiles can be used to extend base images for buildpacks builds">
+<meta property="og:description" content="Dockerfiles can be used to extend base images for buildpacks builds.">
 <meta property="og:type" content="article">
 <meta property="og:image" content="https://buildpacks.io/images/buildpacks-social-card.jpg">
 <meta property="og:image:alt" content="Buildpacks project logo">

docs/features/index.html

@@ -709,24 +709,23 @@ <h1 class="title">Features</h1>
 
 
           <h2><a href="https://buildpacks.io/docs/features/dockerfiles/" class="">Dockerfiles</a></h2>
-          <p class="m-1">Dockerfiles can be used to extend base images for buildpacks builds</p>
+          <p class="m-1">Dockerfiles can be used to extend base images for buildpacks builds.</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/features/dockerfiles/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/features/reproducibility/" class="">Reproducibility</a></h2>
-          <p class="m-1"> The Cloud Native Buildpacks project aims to create &ldquo;Reproducible Builds&rdquo; of container images. For image creation commands (builder create, buildpack package, build) pack creates container images in a reproducible fashion. &ldquo;Reproducible&rdquo; is hard to define but we&rsquo;ll do so by example and with a few caveats:
-</p>
+          <p class="m-1">The Cloud Native Buildpacks project aims to create &ldquo;Reproducible Builds&rdquo; of container images. For image creation commands (<code>builder create</code>, <code>buildpack package</code>, <code>build</code>) <code>pack</code> creates container images in a reproducible fashion. &ldquo;Reproducible&rdquo; is hard to define but we&rsquo;ll do so by example and with a few caveats:</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/features/reproducibility/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/features/bill-of-materials/" class="">Software Bill of Materials</a></h2>
-          <p class="m-1">A Software Bill-of-Materials (SBoM) gives you a layer-by-layer view of what&rsquo;s inside your container in a variety of formats.</p>
+          <p class="m-1">A <code>Software Bill-of-Materials</code> (<code>SBoM</code>) gives you a layer-by-layer view of what’s inside your container in a variety of formats.</p>
 
 
             <div class="text-md-right">

docs/features/index.xml

@@ -12,7 +12,7 @@
       <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
 
       <guid>https://buildpacks.io/docs/features/dockerfiles/</guid>
-      <description>Dockerfiles can be used to extend base images for buildpacks builds</description>
+      <description>Dockerfiles can be used to extend base images for buildpacks builds.</description>
     </item>
 
     <item>

docs/operator-guide/index.html

@@ -709,17 +709,15 @@ <h1 class="title">Operator Guide</h1>
 
 
           <h2><a href="https://buildpacks.io/docs/operator-guide/create-a-builder/" class="">Create a builder</a></h2>
-          <p class="m-1">Creating a custom builder allows you to control what buildpacks are used and what image apps are based on.
-</p>
+          <p class="m-1">Creating a custom <a href="/docs/concepts/components/builder/">builder</a> allows you to control what buildpacks are used and what image apps are based on.</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/operator-guide/create-a-builder/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/operator-guide/create-a-stack/" class="">Create a stack</a></h2>
-          <p class="m-1">Creating a custom stack allows you to configure the base images for the build-time environment for your builder and the run-time for your application.
-</p>
+          <p class="m-1">Creating a custom <a href="/docs/concepts/components/stack/">stack</a> allows you to configure the base images for the build-time environment for your <a href="/docs/concepts/components/builder/">builder</a> and the run-time for your application.</p>
 
 
             <div class="text-md-right">

docs/reference/index.html

@@ -734,8 +734,9 @@ <h2><a href="https://buildpacks.io/docs/reference/config/" class="">Configuratio
 
 
           <h2><a href="https://buildpacks.io/docs/reference/spec/" class="">Specification</a></h2>
-          <p class="m-1">This section provides an overview of the Cloud Native Buildpack API specification. Most buildpack users won&rsquo;t need this information unless they are writing a buildpack or a platform that supports buildpacks.
-</p>
+          <p class="m-1">This section provides an overview of the Cloud Native Buildpack API specification. Most
+buildpack users won&rsquo;t need this information unless they are writing a buildpack or
+a platform that supports buildpacks.</p>
 
 
 

docs/reference/spec/index.html

@@ -712,9 +712,12 @@ <h1 class="title">Specification</h1>
 
 
           <h2><a href="https://buildpacks.io/docs/reference/spec/migration/" class="">Migration</a></h2>
-          <p class="m-1">This section provides a series of guides for migrating from one version of the Cloud Native Buildpack API specification (either buildpack or platform) to the next. Most buildpack users won&rsquo;t need this information unless they are writing a buildpack or a platform that supports buildpacks.
-Each guide describes changes from the previous minor, who these changes impact, as well as any actions that may be necessary.
-</p>
+          <p class="m-1"><p>This section provides a series of guides for migrating from one version of the
+Cloud Native Buildpack API specification (either buildpack or platform) to the next. Most
+buildpack users won&rsquo;t need this information unless they are writing a buildpack or
+a platform that supports buildpacks.</p>
+<p>Each guide describes changes from the previous minor, who these changes impact,
+as well as any actions that may be necessary.</p></p>
 
 
 
@@ -793,26 +796,26 @@ <h2><a href="https://buildpacks.io/docs/reference/spec/migration/" class="">Migr
 
 
           <h2><a href="https://buildpacks.io/docs/reference/spec/buildpack-api/" class="">Buildpack API</a></h2>
-          <p class="m-1">This specification defines the interface between a buildpack and the environment that runs it. This API will be used by buildpack authors.
-</p>
+          <p class="m-1">This specification defines the interface between a buildpack and the environment that runs it.
+This API will be used by buildpack authors.</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/reference/spec/buildpack-api/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/reference/spec/distribution-api/" class="">Distribution API</a></h2>
-          <p class="m-1">This specification defines the artifact format, delivery mechanism, and order resolution process for buildpacks.
-</p>
+          <p class="m-1">This specification defines the artifact format, delivery mechanism, and order resolution process for buildpacks.</p>
 
 
             <div class="text-md-right">
               <a class="small text-pink mr-md-3 text-decoration-none" href="https://buildpacks.io/docs/reference/spec/distribution-api/">Learn more →</a>
             </div>
 
           <h2><a href="https://buildpacks.io/docs/reference/spec/platform-api/" class="">Platform API</a></h2>
-          <p class="m-1">This specification defines the interface between the buildpack execution environment, referred to as the lifecycle, and a platform that supports it. This API is used by platform implementors.
-</p>
+          <p class="m-1">This specification defines the interface between the buildpack execution environment,
+referred to as the <em>lifecycle</em>, and a platform that supports it.
+This API is used by platform implementors.</p>
 
 
             <div class="text-md-right">