build: restructure the base image page

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

content/build/building/base-images.md

@@ -1,5 +1,5 @@
 ---
-title: Create a base image
+title: Base images
 description: Learn about base images and how they're created
 keywords: images, base image, examples
 aliases:
@@ -13,51 +13,35 @@ All Dockerfiles start from a base image.
 A base is the image that your image extends.
 It refers to the contents of the `FROM` instruction in the Dockerfile.
 
-The following Dockerfile example uses the `python` Docker Official Image as a base image.
-Each subsequent instruction in the Dockerfile extends the base image.
-
 ```dockerfile
-FROM python:3-alpine
+FROM debian
-WORKDIR /src
-COPY requirements.txt .
-RUN pip install -r requirements.txt
 ```
 
+For most cases, you don't need to create your own base image. Docker Hub
+contains a vast library of Docker images that are suitable for use as a base
+image in your build. [Docker Official Images](../../trusted-content/official-images/_index.md)
+are specifically designed as a set of hardened, battle-tested images that
+supports a wide variety of platforms, languages, and frameworks. There are also
+[Docker Verified Publisher](https://hub.docker.com/search?q=&image_filter=store)
+images, created by trusted publishing partners, verified by Docker.
+
+## Create a base image
+
 If you need to completely control the contents of your image, you can create
-your own base image or use the special `FROM scratch` base:
+your own base image from a Linux distribution of your choosing, or use the
+special `FROM scratch` base:
 
 ```dockerfile
 FROM scratch
 ```
 
-This page shows you how to create your own base image.
+The `scratch` image is typically used to create minimal images containing only
-The specific process depends on the Linux distribution you want to package.
+just what an application needs. See [Create a minimal base image using scratch](#create-a-minimal-base-image-using-scratch).
 
-## Create a full image using tar
+To create a distribution base image, you can use a root filesystem, packaged as
-
+a `tar` file, and import it to Docker with `docker import`. The process for
-In general, start with a working machine that is running
+creating your own base image depends on the Linux distribution you want to
-the distribution you'd like to package as a base image, though that is
+package. See [Create a full image using tar](#create-a-full-image-using-tar).
-not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap),
-which you can also use to build Ubuntu images.
-
-For example, to create an Ubuntu base image:
-
-```dockerfile
-$ sudo debootstrap focal focal > /dev/null
-$ sudo tar -C focal -c . | docker import - focal
-
-sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3
-
-$ docker run focal cat /etc/lsb-release
-
-DISTRIB_ID=Ubuntu
-DISTRIB_RELEASE=20.04
-DISTRIB_CODENAME=focal
-DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS"
-```
-
-There are more example scripts for creating base images in
-[the Moby GitHub repository](https://github.com/moby/moby/blob/master/contrib).
 
 ## Create a minimal base image using scratch
 
@@ -104,9 +88,33 @@ When building a base image, or any image, this is an important aspect to
 consider. And this is why creating a base image using `FROM scratch` can be
 difficult, for anything other than small, simple programs. On the other hand,
 it's also important to include only the things you need in your image, to
-reduce the image size and attack surface. In most cases, your best option is
+reduce the image size and attack surface.
-to base your images on a suitable tag of a
+
-[Docker Official Image](../../trusted-content/official-images.md).
+## Create a full image using tar
+
+In general, start with a working machine that is running
+the distribution you'd like to package as a base image, though that is
+not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap),
+which you can also use to build Ubuntu images.
+
+For example, to create an Ubuntu base image:
+
+```dockerfile
+$ sudo debootstrap focal focal > /dev/null
+$ sudo tar -C focal -c . | docker import - focal
+
+sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3
+
+$ docker run focal cat /etc/lsb-release
+
+DISTRIB_ID=Ubuntu
+DISTRIB_RELEASE=20.04
+DISTRIB_CODENAME=focal
+DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS"
+```
+
+There are more example scripts for creating base images in
+[the Moby GitHub repository](https://github.com/moby/moby/blob/master/contrib).
 
 ## More resources
 

content/guides/docker-concepts/building-images/multi-stage-builds.md

@@ -325,7 +325,7 @@ Now that you have the project, you’re ready to create the `Dockerfile`.
 
 * [Multi-stage builds](/build/building/multi-stage/)
 * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/)
-* [Creating a base image](/build/building/base-images/)
+* [Base images](/build/building/base-images/)
 * [Spring Boot Docker](https://spring.io/guides/topicals/spring-boot-docker)
 
 

content/guides/docker-concepts/building-images/writing-a-dockerfile.md

@@ -142,7 +142,7 @@ To learn more about writing a Dockerfile, visit the following resources:
 
 * [Dockerfile reference](/reference/dockerfile/)
 * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/)
-* [Create your own base image](/build/building/base-images/)
+* [Base images](/build/building/base-images/)
 * [Getting started with Docker Init](/reference/cli/docker/init/)
 
 ## Next steps

content/language/golang/build-images.md

@@ -113,7 +113,7 @@ has all necessary tools and libraries to compile and run a Go application.
 
 > **Note**
 >
-> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](../../build/building/base-images.md).
+> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](../../build/building/base-images.md#create-a-base-image).
 > Note, however, that this isn't necessary to continue with your task at hand.
 
 Now that you have defined the base image for your upcoming container image, you

data/toc.yaml

@@ -1884,7 +1884,7 @@ Manuals:
         - path: /build/building/opentelemetry/
           title: OpenTelemetry support
         - path: /build/building/base-images/
-          title: Create your own base image
+          title: Base images
     - sectiontitle: Builders
       section:
         - path: /build/builders/