Clean up platform-operator section

Signed-off-by: Natalie Arellano <[email protected]>
buildpacks · Feb 14, 2024 · a1e2e6c · a1e2e6c
1 parent b302ea2
commit a1e2e6c
Show file tree

Hide file tree

Showing 20 changed files with 72 additions and 37 deletions.
diff --git a/content/docs/for-app-developers/concepts/base-images/build.md b/content/docs/for-app-developers/concepts/base-images/build.md
@@ -7,4 +7,8 @@ The **build image** provides the base image from which the build environment is
 
 <!--more-->
 
-The build environment is the containerized environment in which the [lifecycle][lifecycle] (and thereby [buildpacks][buildpack]) are executed.
+The build environment is the containerized environment in which the [lifecycle]
+(and thereby [buildpacks][buildpack]) are executed.
+
+[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/
+[buildpack]: /docs/for-app-developers/concepts/buildpack/
diff --git a/content/docs/for-platform-operators/concepts/builder.md b/content/docs/for-platform-operators/concepts/builder.md
@@ -1,15 +1,16 @@
 +++
-title="Builder"
-weight=1
-summary="A builder is an image that contains all the components necessary to execute a build. A builder image is created by taking a build image and adding a lifecycle, buildpacks, and files that configure aspects of the build including the buildpack detection order and the location(s) of the run image"
+title="What is a builder?"
+weight=2
 aliases=[
     "/docs/using-pack/working-with-builders/"
 ]
 +++
 
-## What is a builder?
+A `builder` is an OCI image containing
+an ordered combination of [buildpacks][buildpack] and
+a build-time base image, a [lifecycle] binary, and a reference to a runtime base image.
 
-{{< param "summary" >}}
+<!--more-->
 
 ![create-builder diagram](/docs/for-platform-operators/concepts/create-builder.svg)
 
@@ -27,6 +28,6 @@ A builder consists of the following components:
 To learn how to create your own builder, see our [Operator's Guide][operator-guide].
 
 [builder-config]: /docs/reference/builder-config/
-[operator-guide]: /docs/for-platform-operators/
 [buildpack]: /docs/for-platform-operators/concepts/buildpack/
 [lifecycle]: /docs/for-platform-operators/concepts/lifecycle/
+[operator-guide]: /docs/for-platform-operators/
diff --git a/content/docs/for-platform-operators/concepts/buildpack.md b/content/docs/for-platform-operators/concepts/buildpack.md
@@ -1,11 +1,9 @@
 +++
-title="Buildpack"
-weight=2
+title="What is a buildpack?"
+weight=1
 +++
 
-## What is a buildpack?
-
-A buildpack is a set of executables that inspects your app source code and creates a plan to build and run your application.
+A `buildpack` is software that examines your source code and determines the best way to build it.
 
 <!--more-->
 

diff --git a/content/docs/for-platform-operators/concepts/dockerfiles.md b/content/docs/for-platform-operators/concepts/dockerfiles.md
@@ -1,8 +1,9 @@
 +++
-title="Dockerfiles"
+title="What are image extensions?"
+weight=99
 +++
 
-Dockerfiles can be used to extend base images for buildpacks builds.
+Image extensions generate Dockerfiles that can be used to extend base images for buildpacks builds.
 
 <!--more-->
 

diff --git a/content/docs/for-platform-operators/concepts/lifecycle/_index.md b/content/docs/for-platform-operators/concepts/lifecycle/_index.md
@@ -1,12 +1,12 @@
 +++
-title="Lifecycle"
+title="What is the lifecycle?"
 weight=3
 include_summaries=true
 
 +++
 
 ## What is the lifecycle?
 
-The lifecycle orchestrates buildpack execution, then assembles the resulting artifacts into a final app image.
+The `lifecycle` orchestrates buildpack execution, then assembles the resulting artifacts into an OCI image.
 
 <!--more-->
diff --git a/...ors/how-to/prepare-build-inputs/_index.md → ...m-operators/how-to/build-inputs/_index.md b/...ors/how-to/prepare-build-inputs/_index.md → ...m-operators/how-to/build-inputs/_index.md
diff --git a/content/docs/for-platform-operators/how-to/build-inputs/create-builder/_index.md b/content/docs/for-platform-operators/how-to/build-inputs/create-builder/_index.md
@@ -0,0 +1,10 @@
++++
+title="Create a builder"
+weight=1
+include_summaries=true
++++
+
+A [builder][builder] is an OCI image with all the inputs needed for a buildpacks build, including
+the build-time base image, a reference to a runtime base image, a lifecycle, and a set of buildpacks.
+
+[builder]: /docs/for-platform-operators/concepts/builder
diff --git a/...how-to/prepare-build-inputs/build-base.md → ...build-inputs/create-builder/build-base.md b/...how-to/prepare-build-inputs/build-base.md → ...build-inputs/create-builder/build-base.md
@@ -1,8 +1,10 @@
 +++
 title="Create a build base image"
-weight=2
+weight=1
 +++
 
+The build-time base image provides the OS-level dependencies for buildpacks at build-time.
+
 <!--more-->
 
 ## Define a build base image for your CNB build

diff --git a/...rs/how-to/prepare-build-inputs/builder.md → ...to/build-inputs/create-builder/builder.md b/...rs/how-to/prepare-build-inputs/builder.md → ...to/build-inputs/create-builder/builder.md
@@ -1,10 +1,9 @@
 +++
-title="Create a builder"
-weight=1
+title="Putting it all together"
+weight=3
 +++
 
-A [builder][builder] is an OCI image with all the inputs needed for a buildpacks build, including 
-the build-time base image, a reference to a runtime base image, a lifecycle, and a set of buildpacks.
+After you have created a build-time base image and a runtime base image, you are ready to create your builder!
 
 <!--more-->
 

diff --git a/...how-to/prepare-build-inputs/extensions.md → ...build-inputs/create-builder/extensions.md b/...how-to/prepare-build-inputs/extensions.md → ...build-inputs/create-builder/extensions.md
@@ -3,6 +3,8 @@ title="Specify an image extension in a builder"
 weight=101
 +++
 
+If you are using extensions, here is how to include them in a builder.
+
 <!--more-->
 
 You're pretty sharp, and you know what your buildpack users will need.

diff --git a/...s/how-to/prepare-build-inputs/run-base.md → ...o/build-inputs/create-builder/run-base.md b/...s/how-to/prepare-build-inputs/run-base.md → ...o/build-inputs/create-builder/run-base.md
@@ -1,8 +1,10 @@
 +++
 title="Create a run base image"
-weight=3
+weight=2
 +++
 
+The runtime base image provides the OS-level dependencies for applications at runtime.
+
 <!--more-->
 
 ## Define a run base image for your CNB build

diff --git a/...erators/how-to/declare-source-metadata.md → ...o/build-inputs/declare-source-metadata.md b/...erators/how-to/declare-source-metadata.md → ...o/build-inputs/declare-source-metadata.md
@@ -1,13 +1,14 @@
 +++
 title="Declare source metadata"
 weight=3
-summary="Conventions for declaring information about application source code, to be included in the application image."
+summary="Declare information about application source code, to be included as metadata in the application image."
 tags=["spec:platform/0.6", "spec:project-descriptor/0.2"]
 +++
 
 ## Summary
 
-The following are conventions for declaring different type of source inputs. This information is provided to the [lifecycle][lifecycle] using [project-metadata.toml][project-metadata].
+The following are conventions for declaring different type of source inputs.
+This information is provided to the [lifecycle][lifecycle] using [project-metadata.toml][project-metadata].
 
 ## Sources
 

diff --git a/...tors/how-to/prepare-build-inputs/stack.md → ...rm-operators/how-to/build-inputs/stack.md b/...tors/how-to/prepare-build-inputs/stack.md → ...rm-operators/how-to/build-inputs/stack.md
@@ -1,16 +1,17 @@
 +++
-title="Create a stack"
-weight=4
+title="Create a stack (deprecated)"
+weight=99
 +++
 
+A stack is the grouping together of the build and run base images, represented by a unique ID.
+
 <!--more-->
 
 **Note**: As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.
 
 You can still configure the build and run base images for your CNB build.
-To find out how, see [create a build base image](/docs/for-platform-operators/how-to/prepare-build-inputs/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/prepare-build-inputs/run-base/).
+To find out how, see [create a build base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base/).
 
-A stack is the grouping together of the build and run base images, represented by a unique ID.
 A stack ID identifies the configuration for the build and run base images, and it used to determined compatibility with available buildpacks, and rebasability when updated run images are available.
 If you're on an older Platform API version, you may still need to create a custom stack.
 To find out how, read on...
@@ -26,7 +27,7 @@ Before we get started, make sure you've got the following installed:
 ## Creating a custom stack
 
 We will create a sample stack based on `Ubuntu Jammy Jellyfish`. To create a custom stack, we need to create customized build and run images.
-To find out how, see [create a build base image](/docs/for-platform-operators/how-to/prepare-build-inputs/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/prepare-build-inputs/run-base/), then come back here.
+To find out how, see [create a build base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/build-base/) and [create a run base image](/docs/for-platform-operators/how-to/build-inputs/create-builder/run-base/), then come back here.
 
 ## Choose your stack ID
 

diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/circleci.md b/content/docs/for-platform-operators/how-to/integrate-ci/circleci.md
@@ -3,7 +3,9 @@ title="CircleCI"
 weight=3
 +++
 
-[CircleCI][circleci] is a continuous integration and delivery platform. The CNB project maintains an integration, called an [orb](https://circleci.com/orbs/), 
+[CircleCI][circleci] is a continuous integration and delivery platform.
+
+The CNB project maintains an integration, called an [orb](https://circleci.com/orbs/), 
 which allows users to run [pack][pack] commands inside their pipelines.
 
 <!--more-->

diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/gitlab.md b/content/docs/for-platform-operators/how-to/integrate-ci/gitlab.md
@@ -3,8 +3,9 @@ title="Gitlab Auto DevOps"
 weight=4
 +++
 
-[Gitlab][about-gitlab] is a web based DevOps platform. It uses [`pack`][pack] as part of the [Auto DevOps][devops] feature, to
-build applications prior to deploying them.
+[Gitlab][about-gitlab] is a web-based DevOps platform. The [Auto DevOps][devops] feature uses [`pack`][pack]
+to build applications prior to deploying them.
+
 <!--more-->
 
 ## Use

diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/kpack.md b/content/docs/for-platform-operators/how-to/integrate-ci/kpack.md
@@ -3,7 +3,10 @@ title="kpack"
 weight=2
 +++
 
-[kpack][kpack] is a Kubernetes native platform, belonging to the [Buildpacks Community](https://github.com/buildpacks-community) organization. It utilizes unprivileged Kubernetes primitives to provide builds of OCI images as a platform implementation of Cloud Native Buildpacks (CNB).
+[kpack][kpack] is a Kubernetes-native platform that uses unprivileged Kubernetes primitives to perform buildpacks builds and keep application images up-to-date.
+
+[kpack][kpack] is part of the [Buildpacks Community](https://github.com/buildpacks-community) organization.
+
 <!--more-->
 
 ## Use 

diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/pack/_index.md b/content/docs/for-platform-operators/how-to/integrate-ci/pack/_index.md
@@ -6,7 +6,8 @@ aliases=["/docs/install-pack/", "/docs/tools/pack/cli/install/"]
 weight=1
 +++
 
-Pack is a tool maintained by the Cloud Native Buildpacks project to support the use of buildpacks. 
+Pack is a CLI tool maintained by the CNB project to support the use of buildpacks.
+
 <!--more-->
 
 It enables the following functionality:

diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/piper.md b/content/docs/for-platform-operators/how-to/integrate-ci/piper.md
@@ -3,7 +3,10 @@ title='Project "Piper"'
 weight=5
 +++
 
-[Project "Piper"][piper] (maintained by [SAP][sap]) is a set of ready-made Continuous Delivery pipelines for direct use in your project. It now also implements the CNB Platform spec as a step and makes it available in your Jenkins pipeline.
+[Project "Piper"][piper] is a set of ready-made continuous delivery pipelines for direct use in your project.
+It now also implements the CNB Platform spec as a step and makes it available in your Jenkins pipeline.
+
+[Project "Piper"][piper] is maintained by [SAP][sap].
 
 <!--more-->
 

diff --git a/content/docs/for-platform-operators/how-to/integrate-ci/tekton.md b/content/docs/for-platform-operators/how-to/integrate-ci/tekton.md
@@ -3,8 +3,10 @@ title="Tekton"
 weight=6
 +++
 
-[Tekton][tekton] is an open-source CI/CD system platform implementation running on k8s. There are two Tekton `tasks`
-maintained by the CNB project, both of which use the [lifecycle][lifecycle] directly (i.e. they do not use `pack`).
+[Tekton][tekton] is an open-source CI/CD system running on k8s.
+
+The CNB project has created two reference "tasks" for performing buildpacks builds,
+both of which use the [lifecycle][lifecycle] directly (i.e. they do not use `pack`).
 
 <!--more-->
 

diff --git a/content/docs/for-platform-operators/tutorials/lifecycle/_index.md b/content/docs/for-platform-operators/tutorials/lifecycle/_index.md
@@ -4,3 +4,5 @@ weight=1
 expand=true
 include_summaries=true
 +++
+
+Coming soon! In the meantime check out this excellent [blog post](https://medium.com/buildpacks/unpacking-cloud-native-buildpacks-ff51b5a767bf) from our community.