docs: more language refresh

Signed-off-by: Mathias Bogaert <[email protected]>

Author: analytically

lit/docs/auth.lit

@@ -3,11 +3,11 @@
 \use-plugin{concourse-docs}
 \split-sections
 
-A single Concourse installation can accomodate many projects and users.
+A single Concourse installation can accommodate many projects and users.
 
 Pipelines, builds, and all other user data are owned by \italic{teams}. A team
-is just a conceptual owner and a separate namespace, tied to an authorization
-config. For example, a team may authorize all members of the \code{concourse}
+is simply a conceptual owner and separate namespace, tied to an authorization
+configuration. For example, a team may authorize all members of the \code{concourse}
 GitHub organization to be a \reference{team-member-role}{member}.
 
 When a user authenticates, each team's authorization config is checked against
@@ -29,37 +29,36 @@ access control for future requests.
   users, see \reference{fly-expose-pipeline}.
 
   Even with a pipeline exposed, all build logs are hidden by default. This is
-  because CI jobs are prone to leaking credentials and other...unsavory
-  information. After you've determined that a job's builds should be safe for
-  public consumption, you can set \reference{schema.job.public}{\code{public: true}}
-  on the job in your pipeline.
+  because CI jobs may leak credentials and other sensitive information.
+  After you've determined that a job's builds are safe for public consumption,
+  you can set \reference{schema.job.public}{\code{public: true}} on the job
+  in your pipeline.
 }
 
 \section{
   \title{Security Caveats}{teams-caveats}
 
-  At present, teams only provide \italic{trusted multi-tenancy}. This means it
+  At present, teams only provide \italic{trusted multi-tenancy}. This means they
   should be used for cases where you know and trust who you're allowing access
   into your Concourse cluster.
 
-  There are a few reasons it'd be a bad idea to do otherwise:
+  There are a few reasons it would be a bad idea to do otherwise:
 
   \list{
-    Any team can run builds with \reference{schema.task.privileged} tasks. A bad
-    actor in the mix could easily use this to harm your workers and your
+    Any team can run builds with \reference{schema.task.privileged} tasks. A malicious
+    actor could easily use this to harm your workers and your
     cluster.
 
-    In the future, we'll probably have this as a flag on a team, indicating
+    In the future, we'll likely add this as a flag on a team, indicating
     whether they're permitted to run privileged builds.
   }{
     There are no networking restrictions in place, and traffic to and from the
     workers is currently unencrypted and unauthorized. Anyone could run a task
-    that does horrible things to your worker's containers, possibly stealing
+    that does harmful things to your worker's containers, potentially stealing
     sensitive information.
 
     This can be remedied with configuration specified on Garden to restrict
     access to the internal network, but this is not detailed in our docs, and
-    we'll probably want to find a better answer than configuration in the
-    future.
+    we'll likely want to find a better solution in the future.
   }
-}
+}

lit/docs/builds.lit

@@ -2,7 +2,7 @@
 
 \use-plugin{concourse-docs}
 
-A build is an execution of a \italic{build plan}, which is either
+A build is an execution of a \italic{build plan}, which is either:
 
 \list{
   configured as a sequence of \reference{steps}{steps} in a \reference{jobs}{job}
@@ -14,37 +14,37 @@ A build is an execution of a \italic{build plan}, which is either
 
 Containers and volumes are created as \reference{get-step}s,
 \reference{put-step}s, and \reference{task-step}s run. When a build completes
-successfully, these containers go away.
+successfully, these containers are removed.
 
-A failed build's containers and volumes are kept around so that you can debug
-the build via \reference{fly-intercept}. If the build belongs to a
-\reference{jobs}{job}, the containers will go away when the next build starts.
-If the build is a one-off, its containers will be removed immediately, so make
-sure you intercept while it's running, if you want to debug.
+For failed builds, containers and volumes are preserved to allow debugging
+via \reference{fly-intercept}. If the build belongs to a
+\reference{jobs}{job}, the containers will be removed when the next build starts.
+If the build is a one-off, its containers will be removed immediately, so make sure
+you intercept while it's running if you want to debug.
 
 \table-of-contents
 
 \section{
   \title{Rerunning a Build}{build-rerunning}
 
-  Concourse supports build rerunning, which means to run a new build using the
+  Concourse supports build rerunning, which means running a new build using the
   exact same set of input versions as the original build. There are two ways to
   rerun a build: through the web UI on the builds page and through the
-  \reference{fly-rerun-build}.
+  \reference{fly-rerun-build} command.
 
-  When a build is rerun, it will create a new build using the name of the
+  When a build is rerun, it creates a new build using the name of the
   original build with the rerun number appended to it, e.g. \code{3.1} for the
   first rerun of build \code{3}.
 
   Rerun builds are ordered chronologically after the original build, rather
   than becoming a new "latest" build. Similarly, when the scheduler is
   resolving \reference{schema.get.passed}{\code{passed}} constraints
   that reference a job with rerun builds, those rerun builds are
-  processed in this same order. This ensures that the versions, which made it
-  through a rerun build, do not become the new "latest versions". Instead, they
+  processed in this same order. This ensures that versions which made it
+  through a rerun build do not become the new "latest versions". Instead, they
   act as if the original build had succeeded at its point in the build history.
 
-  This may sound a little confusing, but the summary is that reruns should
+  This may sound a little confusing, but the key point is that reruns should
   behave as if they replace the original failed build.
 
   \section{
@@ -56,11 +56,11 @@ sure you intercept while it's running, if you want to debug.
     with.
 
     This means that if the \reference{schema.job.plan} has changed in a way
-    that is backwards-incompatible, the rerun build may error. For example, if
+    that is backwards-incompatible, the rerun build may fail. For example, if
     a new input is added, its version will not be available as the original
     build did not use it.
 
-    There are future plans to have reruns execute the exact build plan from the
+    There are plans to have reruns execute the exact build plan from the
     original build. If you are interested in tracking the progress for the
     second pass at rerunning builds - or contributing yourself! - the project
     epic is called \link{Build Lifecycle
@@ -86,7 +86,7 @@ sure you intercept while it's running, if you want to debug.
   This can be useful for periodically monitoring the state of a job. The output
   also works well with tools like \code{awk} and \code{grep}.
 
-  By default the most recent 50 builds are shown. To see more builds, use
+  By default, the most recent 50 builds are shown. To see more builds, use
   the \code{-c} flag, like so:
 
   \codeblock{bash}{{
@@ -97,16 +97,16 @@ sure you intercept while it's running, if you want to debug.
 \section{
   \title{\code{fly intercept}}{fly-intercept}
 
-  Sometimes it's helpful to connect to the machine where tasks run. This way you
-  can either profile or inspect tasks, or see the state of the machine at the
-  end of a run. Due to Concourse running tasks in containers on remote
-  machines this would typically be hard to access.
+  Sometimes it's helpful to connect to the machine where tasks run. This allows you
+  to profile or inspect tasks, or see the state of the machine at the
+  end of a run. Since Concourse runs tasks in containers on remote
+  machines, these would typically be difficult to access.
 
-  To this end, there is a \code{fly intercept} command that will give you an
+  The \code{fly intercept} command gives you an
   interactive shell inside the specified container. Containers are identified
-  by a few things, so you may need to specify a few flags to hone down the
-  results. If there are multiple containers that the flags could refer to, an
-  interactive prompt will show up allowing you to disambiguate.
+  by several attributes, so you may need to specify multiple flags to narrow down the
+  results. If there are multiple matching containers, an
+  interactive prompt will appear allowing you to select one.
 
   For example, running the following will run a task and then enter the
   finished task's container:
@@ -118,15 +118,15 @@ sure you intercept while it's running, if you want to debug.
 
   \aside{
     When intercepting a task running on a Windows worker, you will need to
-    specifically tell fly to to run \code{powershell}:
+    specifically tell fly to run \code{powershell}:
 
     \codeblock{bash}{{
     $ fly -t example intercept powershell
     }}
   }
 
-  Containers are around for a short time after a build finishes in order to
-  allow people to intercept them.
+  Containers remain available for a short time after a build finishes to
+  allow for interception.
 
   You can also intercept builds that were run in your pipeline. By using
   \code{--job}, \code{--build}, and \code{--step} you can intercept a specific
@@ -138,11 +138,11 @@ sure you intercept while it's running, if you want to debug.
   }}
 
   Note that \code{--build} can be omitted, and will default to the most recent
-  build of the job. One-off builds can be reached by passing in their build ID
-  to \code{--build} which can be found on the build list page.
+  build of the job. One-off builds can be reached by passing their build ID
+  to \code{--build}, which can be found on the build list page.
 
-  The \code{--step} flag can also be omitted; this will let you pick the step
-  interactively, if you don't know the exact name.
+  The \code{--step} flag can also be omitted; this will let you select the step
+  interactively if you don't know the exact name.
 
   Resource checking containers can also be intercepted with \code{--check} or
   \code{-c}:
@@ -157,7 +157,7 @@ sure you intercept while it's running, if you want to debug.
   current build's task, even as the "current build" changes.
 
   The working directory and any relevant environment variables (e.g. those
-  having come from \reference{schema.task.params}) used by the original process will
+  from \reference{schema.task.params}) used by the original process will
   also be used for the process run by intercept.
 }
 
@@ -178,26 +178,26 @@ sure you intercept while it's running, if you want to debug.
   \title{\code{fly watch}}{fly-watch}
 
   Concourse emits streaming colored logs on the website, but it can be helpful
-  to have the logs available to the command line (e.g. so that they can be
+  to have the logs available in the command line (e.g. so they can be
   processed by other commands).
 
-  The \code{watch} command can be used to do just this. You can also view
+  The \code{watch} command can be used for this purpose. You can view
   builds that are running in your pipeline, or builds that have already
   finished.
 
   Note that unlike \reference{fly-execute}, killing \code{fly watch} via
   \code{SIGINT} or \code{SIGTERM} will \italic{not} abort the build.
 
-  To watch the most recent one-off build, just run \code{fly watch} with no
-  arguments. To watch a specific build (one-off or no), pass \code{--build}
+  To watch the most recent one-off build, run \code{fly watch} with no
+  arguments. To watch a specific build (one-off or not), pass \code{--build}
   with the ID of the build to watch. This ID is available at the start of
   \reference{fly-execute}'s output or by browsing to the builds list in the web
   UI.
 
-  By using the \code{--job} and \code{--build} flags you can pick out a
+  By using the \code{--job} and \code{--build} flags, you can select a
   specific build of a job to watch. For example, the following command will
-  either show the archived logs for an old build, if it has finished running, or
-  it will stream the current logs, if the build is still in progress.
+  either show the archived logs for an old build if it has finished running, or
+  it will stream the current logs if the build is still in progress.
 
   \codeblock{bash}{{
   $ fly -t example watch --job my-pipeline/tests --build 52
@@ -206,5 +206,7 @@ sure you intercept while it's running, if you want to debug.
   If the \code{--job} flag is specified and \code{--build} is omitted, the most
   recent build of the specified job will be selected.
 
-  If there is a mismatch between the \code{fly} and \code{web} versions, it is possible to run into \code{failed to parse next event: unknown event type} error. The \code{--ignore-event-parsing-errors} flag can be passed to ignore such errors. 
-}
+  If there is a mismatch between the \code{fly} and \code{web} versions, you may encounter
+  a \code{failed to parse next event: unknown event type} error. The \code{--ignore-event-parsing-errors}
+  flag can be passed to ignore such errors.
+}

lit/docs/config.lit

@@ -2,16 +2,16 @@
 
 \use-plugin{concourse-docs}
 
-Concourse configuration for things like \reference{pipelines} and
-\reference{tasks} is done through declarative
+Concourse configuration for features like \reference{pipelines} and
+\reference{tasks} is managed through declarative
 \link{YAML}{https://en.wikipedia.org/wiki/YAML} files.
 
-Concourse configuration supports basic variable substitution by way of
+Concourse configuration supports basic variable substitution using
 \reference{vars}{\code{((vars))}}. There is no built-in support for
-fancier templating constructs, e.g. loops and conditionals; users are free to
-use whatever templating system they like.
+more advanced templating constructs such as loops and conditionals; users are free to
+use whatever templating system they prefer.
 
 \table-of-contents
 
 \include-section{config/yaml.lit}
-\include-section{config/basic-schemas.lit}
+\include-section{config/basic-schemas.lit}

lit/docs/getting-started.lit

@@ -1,10 +1,10 @@
 \title{Getting Started}
 
-This tutorial will guide you through the basics of creating Concourse
+This tutorial guides you through the basics of creating Concourse
 pipelines. You will use a local instance of Concourse running on your machine to
 run pipelines.
 
-Before getting started you should have the following installed:
+Before getting started, ensure you have the following installed:
 
 \list{
   \link{Docker}{https://docs.docker.com/get-docker/}
@@ -13,17 +13,17 @@ Before getting started you should have the following installed:
 }
 
 This tutorial assumes you understand what Linux containers are and how to work
-with them. If you know what a Dockerfile is and how to make your own then you're
-probably good to jump into this tutorial. If you're not familiar with Linux
-containers then you may want to \link{get started with
-Docker}{https://docs.docker.com/get-started/} first before diving into this
+with them. If you know what a Dockerfile is and how to create one, you're
+probably ready for this tutorial. If you're not familiar with Linux
+containers, we recommend \link{getting started with
+Docker}{https://docs.docker.com/get-started/} before diving into this
 tutorial.
 
 It will also help if you know how to read YAML. We have a quick
 \reference{intro-to-yaml} if you're not familiar with the syntax.
 
 \aside{
-  If you have any feedback for this tutorial please share it in \link{this
+  If you have any feedback for this tutorial, please share it in \link{this
   GitHub discussion}{https://github.com/concourse/concourse/discussions/7353}
 }
 
@@ -34,4 +34,4 @@ It will also help if you know how to read YAML. We have a quick
 \include-section{getting-started/quickstart.lit}
 \include-section{getting-started/hello-world.lit}
 \include-section{getting-started/inputs-outputs.lit}
-\include-section{getting-started/resources.lit}
+\include-section{getting-started/resources.lit}

lit/docs/how-to-guides.lit

@@ -1,14 +1,14 @@
 \title{How-To Guides}
 
-The following pages are guides that show how to accomplish certain workflows
-within Concourse. Most of the guides will use specific images but you are in no
-way limited to or forced to use these images to accomplish the same task. There
-are many ways to accomplish the same thing in Concourse, so don't let these
-guides limit you in what you think is possible with Concourse.
+The following pages provide guides that show how to accomplish specific workflows
+within Concourse. Most guides use specific images, but you are not limited to
+or required to use these images to accomplish the same tasks. There are many ways
+to accomplish the same goal in Concourse, so don't let these guides limit your
+understanding of what's possible with Concourse.
 
 \split-sections
 \table-of-contents
 
 \include-section{./guides/pipeline-guides.lit}
 \include-section{./guides/git.lit}
-\include-section{./guides/container-images.lit}
+\include-section{./guides/container-images.lit}