Merge pull request #554 from analytically/reword

docs: refresh language, clean up old references

Author: taylorsilva

lit/docs.lit

@@ -2,50 +2,49 @@
 
 \use-plugin{concourse-docs}
 
-Concourse is a pipeline-based continuous thing-doer.
+Concourse is a pipeline-based continuous automation system.
 
-The word "pipeline" is all the rage in CI these days, so being more specific
-about this term is kind of important; Concourse's pipelines are significantly
-different from the rest.
+The term "pipeline" has become widespread in CI discussions, so being precise
+about what this means is important; Concourse's pipelines differ significantly
+from others.
 
 \reference{pipelines} are built around \reference{resources}, which represent
 all external state, and \reference{jobs}, which interact with them. Concourse
-pipelines represent a dependency flow, kind of like distributed
-\code{Makefile}s. Pipelines are designed to be self-contained so as to minimize
-server-wide configuration. Maximizing portability also mitigates risk, making
-it easier for projects to recover from CI disasters.
+pipelines function as dependency flows, similar to distributed
+\code{Makefile}s. Pipelines are designed to be self-contained to minimize
+server-wide configuration. Maximizing portability also reduces risk, making
+it simpler for projects to recover from CI disruptions.
 
 \reference{resources} like the \resource{git} and \resource{s3} are used to
-express source code, dependencies, deployments, and any other external state.
-This interface is also used to model more abstract things like scheduled or
+express source code, dependencies, deployments, and other external states.
+This interface also models more abstract concepts like scheduled or
 interval triggers, via the \resource{time}.
 
-\reference{resource-types} are defined as part of the pipeline itself, making
-the pipelines more self-contained and keeping Concourse itself small and
-generic without resorting to a complicated plugin system.
+\reference{resource-types} are defined within the pipeline itself, making
+the pipelines more self-sufficient while keeping Concourse lean and
+versatile without needing a complex plugin system.
 
 \reference{jobs} are sequences of \reference{get-step}{\code{get}},
 \reference{put-step}{\code{put}}, and \reference{task-step}{\code{task}} steps
 to execute. These \reference{steps}{steps} determine the job's inputs and
 outputs. Jobs are designed to be idempotent and loosely coupled, allowing the
-pipeline to grow with the project's needs without requiring engineers to keep
-too much in their head at a time.
+pipeline to evolve with project needs without requiring engineers to maintain
+too much context simultaneously.
 
 Everything in Concourse runs in a container. Instead of modifying workers to
-install build tools, \reference{tasks} describe their own container image
+install build tools, \reference{tasks} define their own container image
 (typically using Docker images via the \resource{registry-image}).
 
 \inline-header{...What?}
 
-Concourse admittedly has a steeper learning curve at first, and depending on
-your background it might be a lot to take in. A core goal of this project is
-for the curve to flatten out shortly after and result in higher productivity
-and less stress over time.
-
-If this all sounds like gobbeldigook, that's OK - you may want to just continue
-on, start kicking the tires a bit, and use the above as a quick reference of
-the "big picture" as the mental model sets in.
+Concourse admittedly has a steeper learning curve initially, and depending on
+your background it might seem like a lot to grasp. A key goal of this project is
+for that curve to flatten out shortly after and lead to greater productivity
+and reduced stress over time.
 
+If this all sounds confusing, that's OK - you may want to simply continue
+onward, start experimenting a bit, and use the above as a quick reference of
+the "big picture" as your understanding develops.
 
 \include-section{./docs/getting-started.lit}
 \include-section{./docs/install.lit}
@@ -66,4 +65,4 @@ the "big picture" as the mental model sets in.
 \include-section{./docs/internals.lit}
 
 \split-sections
-\table-of-contents
+\table-of-contents

lit/ecosystem.lit

@@ -2,24 +2,24 @@
 
 \use-plugin{concourse-docs}
 
-Concourse is used by a wide variety of businesses, governments, open source
-projects and non-profit organisations. The uses of Concourse are as diverse as
-its user base, and include CI/CD for apps, continuous delivery of
-infrastructure, release integration, automation of tests, and many more!
+Concourse is utilized by a diverse array of businesses, government agencies, open source
+projects and non-profit organizations. The applications of Concourse are as varied as
+its user community, including CI/CD for applications, continuous delivery of
+infrastructure, release integration, test automation, and numerous other use cases!
 
-If you use Concourse, or your business offers Concourse-related services, we'd
-love to hear from you. Please \link{raise a pull
-request}{https://github.com/concourse/docs/pulls} adding your organisation's
-name in lexicographical order to the list below, and help us let the world know
-how many people do things continuously with Concourse.
+If you use Concourse, or your organization offers Concourse-related services, we'd
+appreciate hearing from you. Please \link{submit a pull
+request}{https://github.com/concourse/docs/pulls} adding your organization's
+name in alphabetical order to the list below, and help us showcase how many
+people do things continuously with Concourse.
 
 \section{
   \title{Who Uses Concourse?}{who-uses-concourse}
 
-  These organisations have either added themselves to this list, or whose usage of
-  Concourse is in the public domain. There are many more users of Concourse who
-  are unable to publicly share information about their tech stack (typically banks
-  and security companies).
+  These organizations have either added themselves to this list, or whose use of
+  Concourse is publicly known. There are many additional Concourse users who
+  cannot publicly disclose information about their technology stack (typically financial
+  institutions and security firms).
 
   \ordered-list{
     \link{Altoros}{https://www.altoros.com}
@@ -107,15 +107,17 @@ how many people do things continuously with Concourse.
 \section{
   \title{Service Providers}{service-providers}
 
-  The following organisations offer a range of Concourse-related services, such as
-  training, consultancy, support and managed offerings.
+  The following organizations provide various Concourse-related services, including
+  training, consulting, support and managed solutions.
 
   \list{
     \link{Altoros}{https://www.altoros.com}
   }{
     \link{anynines}{https://www.anynines.com}
   }{
     \link{Armakuni}{https://www.armakuni.com}
+  }{
+    \link{CentralCI}{https://centralci.com}
   }{
     \link{Cycloid}{https://www.cycloid.io}
   }{
@@ -133,15 +135,4 @@ how many people do things continuously with Concourse.
   }{
     \link{VMware Tanzu Labs}{https://tanzu.vmware.com/labs}
   }
-}
-
-\section{
-  \title{Third-Party Tools}{third-party-tools}
-
-  The following tools have documentation on how to use Concourse with their
-  software.
-
-  \list{
-    \link{BrowserStack}{https://www.browserstack.com/automate?utm_source=concourse&utm_medium=partnered} (\link{Docs}{https://www.browserstack.com/docs/automate/selenium/concourse})
-  }
-}
+}

lit/examples.lit

@@ -2,14 +2,14 @@
 
 \use-plugin{concourse-docs}
 
-Configuring self-contained Concourse \reference{pipelines}{pipelines} is a great
-way to try things out before diving into the deeper content.
+Setting up self-contained Concourse \reference{pipelines}{pipelines} is an excellent
+way to experiment before exploring the more comprehensive documentation.
 
-Each example contains a pipeline YAML snippet which can be copy-pasted to a
-local file and configured on your instance via \reference{fly-set-pipeline}.
-From there you may want to poke around and try changing parts of the
-configuration to learn how things work. All the available knobs to turn are
-covered in the \reference{docs}.
+Each example presents a pipeline YAML snippet which can be copied to a
+local file and deployed to your instance via \reference{fly-set-pipeline}.
+From there you can experiment and modify parts of the
+configuration to better understand how everything works. All configuration options are
+detailed in the \reference{docs}.
 
 \include-section{./examples/hello-world.lit}
 \include-section{./examples/serial-job.lit}
@@ -29,8 +29,8 @@ covered in the \reference{docs}.
 \split-sections
 \table-of-contents
 
-For a real-world example, check out \link{Concourse's own
+For a practical real-world example, examine \link{Concourse's own
 pipeline}{https://ci.concourse-ci.org/teams/main/pipelines/concourse} (and its
-\link{config}{https://github.com/concourse/ci/blob/master/pipelines/concourse.yml}):
+\link{configuration}{https://github.com/concourse/ci/blob/master/pipelines/concourse.yml}):
 
-\frame{https://ci.concourse-ci.org/teams/main/pipelines/concourse}{600px}
+\frame{https://ci.concourse-ci.org/teams/main/pipelines/concourse}{600px}

lit/index.lit

@@ -4,38 +4,25 @@
 \styled{index}
 
 \splash-intro{
-  \inline-header{Concourse is an open-source continuous thing-doer.}
+  \inline-header{Concourse is an open-source continuous automation platform.}
 
-  Built on the simple mechanics of \reference{resources}{resources},
-  \reference{tasks}{tasks}, and \reference{jobs}{jobs}, Concourse presents a
-  general approach to automation that makes it great for
+  Centered around the simple mechanics of \reference{resources}{resources},
+  \reference{tasks}{tasks}, and \reference{jobs}{jobs}, Concourse delivers a
+  versatile approach to automation that excels at
   \link{CI}{https://en.wikipedia.org/wiki/Continuous_integration}/\link{CD}{https://en.wikipedia.org/wiki/Continuous_delivery}.
 
   \button{\reference{quick-start}}
 }{
   \download-links
 }
 
-\page-region{light}{Built in the open}{
-  Concourse's \link{RFC process}{https://github.com/concourse/rfcs} and
-  \link{governance model}{https://github.com/concourse/governance} invite
-  anyone to become a contributor, developing the project roadmap by
-  collaborating in the open.
-
-  \rfcs-table{10}{ByTotalReactions}
-
-  Help shape Concourse into a tool that fits your needs by \link{submitting
-  feedback}{https://github.com/concourse/rfcs/#reviewing-rfcs} on the RFCs
-  listed above!
-}
-
-\page-region{light}{Key features}{
-  Concourse is designed to be \link{expressive, versatile, and
-  safe}{https://github.com/concourse/rfcs/blob/master/DESIGN_PRINCIPLES.md},
-  remaining intuitive as the complexity of your project grows.
+\page-region{light}{Core features}{
+  Concourse is engineered to be \link{expressive, versatile, and
+  secure}{https://github.com/concourse/rfcs/blob/master/DESIGN_PRINCIPLES.md},
+  remaining intuitive even as your project complexity grows.
 
   \side-by-side{
-    \inline-header{Configure as code}
+    \inline-header{Code-based configuration}
 
     \codeblock{yaml}{{{
     resources:
@@ -52,45 +39,44 @@
         file: booklit/ci/test.yml
     }}}
   }{
-    \inline-header{Visualize to verify}
+    \inline-header{Visual verification}
 
     \include-template{basic-pipeline-svg}
   }
 
   \side-by-side{
-    A Concourse \reference{pipelines}{pipeline} is like a distributed, continuous
+    A Concourse \reference{pipelines}{pipeline} functions like a distributed, continuous
     \code{Makefile}.
 
-    Each \reference{jobs}{job} has a \reference{schema.job.plan}{build plan}
-    declaring the job's input \reference{resources}{resources} and what to run
-    with them when they change.
+    Each \reference{jobs}{job} contains a \reference{schema.job.plan}{build plan}
+    defining the job's input \reference{resources}{resources} and what actions to perform
+    with them when changes occur.
   }{
-    Your pipeline is then visualized in the web UI, taking only one click to get
-    from a failed job to seeing why it failed.
+    Your pipeline appears visualized in the web UI, requiring just one click to move
+    from a failed job to understanding the cause of failure.
 
-    The visualization provides a "gut check" feedback loop: if it \italic{looks}
+    The visualization provides immediate feedback: if it \italic{looks}
     wrong, it probably \italic{is} wrong.
   }
 
-  \inline-header{A more complicated example...}
+  \inline-header{A more complex example...}
 
-  Jobs can depend on other jobs by configuring
-  \reference{schema.get.passed}{\code{passed}} constraints. The resulting chain
-  of jobs and resources is a dependency graph that continuously pushes your
-  project forward, from source code to production.
+  Jobs can depend on other jobs through \reference{schema.get.passed}{\code{passed}} constraints.
+  The resulting network of jobs and resources creates a dependency graph that continuously
+  advances your project forward, from source code to production.
 
   \include-template{pipeline-image}
 
-  \italic{This particular pipeline can be found in the \link{Booklit
+  \italic{This pipeline example can be found in the \link{Booklit
   repository}{https://github.com/concourse/booklit/blob/8741a4ca3116dcf24c30fedfa78e4aadcaff178a/ci/pipeline.yml}.}
 
-  \splash-example{CI under source control}{
-    All configuration and administration is done using \reference{fly-cli}{the
+  \splash-example{Source-controlled CI}{
+    All configuration and management happens through \reference{fly-cli}{the
     \code{fly} CLI}.
 
-    The \reference{fly-set-pipeline} command pushes the config up to Concourse.
-    Once it looks good, you can then check the file in to source control. This
-    makes it easy to recover your project if the Concourse server burns down.
+    The \reference{fly-set-pipeline} command uploads your configuration to Concourse.
+    Once finalized, you can commit the file to source control, making it easy to
+    recover your project if you migrate to a new Concourse server.
   }{
     \codeblock{sh}{{{
     $ fly -t ci set-pipeline -p booklit -c pipeline.yml
@@ -102,14 +88,13 @@
   }
 
   \splash-example{Reproducible, debuggable builds}{
-    Everything runs in containers, ensuring a clean environment on every run.
+    Everything executes in containers, ensuring a clean environment for each run.
 
-    Each \reference{tasks}{task} specifies its own image, giving it full control
-    over its dependencies, rather than managing packages and state on your
-    workers.
+    Every \reference{tasks}{task} specifies its own image, providing complete control
+    over its dependencies, instead of managing packages on your workers.
 
-    The \reference{fly-intercept} command will pop you right into one of your
-    build's containers, making it easy to troubleshoot flaky builds.
+    The \reference{fly-intercept} command lets you access a build's containers directly,
+    simplifying troubleshooting of problematic builds.
   }{
     \codeblock{sh}{{{
     $ fly -t ci intercept -j booklit/unit -s unit
@@ -123,16 +108,16 @@
     }}}
   }
 
-  \splash-example{Rapid local iteration}{
-    The \reference{fly-execute} command lets you run a build with local changes.
+  \splash-example{Efficient local testing}{
+    The \reference{fly-execute} command enables you to run builds with local modifications.
 
-    This build runs in exactly the same way as it would run in your pipeline,
-    without having to push broken commits until it works.
+    These builds execute exactly as they would in your pipeline, eliminating the
+    need to push incomplete commits while debugging.
 
-    When a build in the pipeline fails, you can run \reference{fly-execute} with
+    When a pipeline build fails, you can use \reference{fly-execute} with
     the \code{-j} flag to run a one-off build with the same inputs as the failed
-    build. You can then replace an input with your local changes with \code{-i}
-    to see if your fix is valid.
+    build. You can then replace an input with your local changes using \code{-i}
+    to test your fix.
   }{
     \codeblock{sh}{{{
     ~/booklit $ fly -t ci execute -c ci/test.yml
@@ -147,7 +132,7 @@
     }}}
   }
 
-  \inline-header{Bring your own integrations}
+  \inline-header{Custom integrations}
 
   \side-by-side{
     \codeblock{yaml}{{{
@@ -170,25 +155,25 @@
       - # ...
     }}}
   }{
-    Concourse does not have a complex plugin system. Instead, it focuses on a
-    single strong abstraction: \reference{resources}{resource}, which are
+    Concourse doesn't rely on a complex plugin system. Instead, it focuses on a
+    single powerful abstraction: \reference{resources}{resource}, which are
     implemented by \reference{resource-types}{resource types}.
 
     The \reference{schema.pipeline.resources} field configures external artifacts
-    that your pipeline will monitor for changes, fetch from, and push to.
+    that your pipeline will monitor for changes, retrieve, and update.
 
-    For example, a resource with type \code{git} refers to a git repository,
+    For instance, a resource with type \code{git} refers to a git repository,
     which will be \code{clone}d in a \reference{get-step} and \code{push}ed to
-    using a \reference{put-step}. Behind the scenes, Concourse will continuously
-    run \code{git fetch} to look for new commits that jobs may want to trigger
+    using a \reference{put-step}. Behind the scenes, Concourse continuously
+    runs \code{git fetch} to check for new commits that jobs might want to trigger
     on.
 
-    At its core, Concourse knows nothing about \code{git}. It comes with a
+    At its foundation, Concourse has no built-in knowledge of \code{git}. It includes a
     \link{\code{git} resource type}{https://github.com/concourse/git-resource}
-    out of the box, but you could just as easily bring your own into your
-    pipeline by setting the \reference{schema.pipeline.resource_types} field.
+    by default, but you can easily integrate your own into your pipeline through
+    the \reference{schema.pipeline.resource_types} field.
 
-    To see what resource types are available, check out the \link{Resource Types
+    To discover available resource types, check out the \link{Resource Types
     catalog}{https://resource-types.concourse-ci.org}!
   }
 }
@@ -198,4 +183,4 @@
 \include-section{./docs.lit}
 \include-section{./examples.lit}
 \include-section{./project.lit}
-\include-section{./ecosystem.lit}
+\include-section{./ecosystem.lit}