From 90e4e14d2f7c04f9bce38462a6952a1d8542481e Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 11:45:45 +0100
Subject: [PATCH 01/26] Disabled resource type link for the time being

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 blog/default.hbs | 2 +-
 html/top.tmpl    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/blog/default.hbs b/blog/default.hbs
index a87d719e..9ef8d9f5 100644
--- a/blog/default.hbs
+++ b/blog/default.hbs
@@ -18,7 +18,7 @@
         <a class="top-link" href="https://concourse-ci.org/docs.html">docs</a>
         <a class="top-link" href="https://concourse-ci.org/examples.html">examples</a>
         <a class="top-link" href="https://concourse-ci.org/project.html">project</a>
-        <a class="top-link" href="https://resource-types.concourse-ci.org">resource types</a>
+        <!-- <a class="top-link" href="https://resource-types.concourse-ci.org">resource types</a> -->
         <a class="top-link active" href="https://blog.concourse-ci.org">blog</a>
         <a class="top-link" href="https://github.com/concourse/concourse/discussions">discuss</a>
       </nav>
diff --git a/html/top.tmpl b/html/top.tmpl
index eb31f27b..291f38b1 100644
--- a/html/top.tmpl
+++ b/html/top.tmpl
@@ -6,7 +6,7 @@
     {{range .Top.Children}}
     <a class="top-link{{if .Contains $}} active{{end}}" href="{{.PrimaryTag | url}}">{{.Title | stripAux | render}}</a>
     {{end}}
-    <a class="top-link" href="https://resource-types.concourse-ci.org">Resource Types</a>
+    <!-- <a class="top-link" href="https://resource-types.concourse-ci.org">Resource Types</a> -->
     <a class="top-link" href="https://blog.concourse-ci.org">blog</a>
     <a class="top-link" href="https://github.com/concourse/concourse/discussions">discuss</a>
 

From 8f37c7272125a3dcbdf5993a2b538fede427c882 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 11:50:43 +0100
Subject: [PATCH 02/26] Create beginners and move Getting Started section

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/beginners.lit                                          | 7 +++++++
 lit/{docs => beginners}/getting-started.lit                | 0
 lit/{docs => beginners}/getting-started/hello-world.lit    | 0
 lit/{docs => beginners}/getting-started/inputs-outputs.lit | 0
 lit/{docs => beginners}/getting-started/quickstart.lit     | 0
 lit/{docs => beginners}/getting-started/resources.lit      | 0
 lit/beginners/whats-next.lit                               | 3 +++
 lit/docs.lit                                               | 1 -
 lit/index.lit                                              | 1 +
 9 files changed, 11 insertions(+), 1 deletion(-)
 create mode 100644 lit/beginners.lit
 rename lit/{docs => beginners}/getting-started.lit (100%)
 rename lit/{docs => beginners}/getting-started/hello-world.lit (100%)
 rename lit/{docs => beginners}/getting-started/inputs-outputs.lit (100%)
 rename lit/{docs => beginners}/getting-started/quickstart.lit (100%)
 rename lit/{docs => beginners}/getting-started/resources.lit (100%)
 create mode 100644 lit/beginners/whats-next.lit

diff --git a/lit/beginners.lit b/lit/beginners.lit
new file mode 100644
index 00000000..2bcff6ad
--- /dev/null
+++ b/lit/beginners.lit
@@ -0,0 +1,7 @@
+\title{Beginners}
+
+\use-plugin{concourse-docs}
+
+
+\include-section{./beginners/getting-started.lit}
+\include-section{./beginners/whats-next.lit}
\ No newline at end of file
diff --git a/lit/docs/getting-started.lit b/lit/beginners/getting-started.lit
similarity index 100%
rename from lit/docs/getting-started.lit
rename to lit/beginners/getting-started.lit
diff --git a/lit/docs/getting-started/hello-world.lit b/lit/beginners/getting-started/hello-world.lit
similarity index 100%
rename from lit/docs/getting-started/hello-world.lit
rename to lit/beginners/getting-started/hello-world.lit
diff --git a/lit/docs/getting-started/inputs-outputs.lit b/lit/beginners/getting-started/inputs-outputs.lit
similarity index 100%
rename from lit/docs/getting-started/inputs-outputs.lit
rename to lit/beginners/getting-started/inputs-outputs.lit
diff --git a/lit/docs/getting-started/quickstart.lit b/lit/beginners/getting-started/quickstart.lit
similarity index 100%
rename from lit/docs/getting-started/quickstart.lit
rename to lit/beginners/getting-started/quickstart.lit
diff --git a/lit/docs/getting-started/resources.lit b/lit/beginners/getting-started/resources.lit
similarity index 100%
rename from lit/docs/getting-started/resources.lit
rename to lit/beginners/getting-started/resources.lit
diff --git a/lit/beginners/whats-next.lit b/lit/beginners/whats-next.lit
new file mode 100644
index 00000000..c1240c48
--- /dev/null
+++ b/lit/beginners/whats-next.lit
@@ -0,0 +1,3 @@
+\title{What's next?}
+
+TBD
\ No newline at end of file
diff --git a/lit/docs.lit b/lit/docs.lit
index a2302d66..0d3c4db3 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -47,7 +47,6 @@ 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.
 
 
-\include-section{./docs/getting-started.lit}
 \include-section{./docs/install.lit}
 \include-section{./docs/auth.lit}
 \include-section{./docs/fly.lit}
diff --git a/lit/index.lit b/lit/index.lit
index fbd1c608..af4999d2 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -195,6 +195,7 @@
 
 \split-sections
 
+\include-section{./beginners.lit}
 \include-section{./docs.lit}
 \include-section{./examples.lit}
 \include-section{./project.lit}

From 7809f6023b59d5c09566c59cc61213eef089e9f5 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 12:08:44 +0100
Subject: [PATCH 03/26] Create separate reference topic

* Add the following topics as reference:
  * fly CLI command (incomplete by the time of writing)
  * Try to make a comprehensive fly CLI reference
  * resource types
* Use "See also" in example as reference (to avoid problems with
  top reference.lit file)

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                  |   3 -
 lit/docs/fly.lit                              | 217 ------------------
 lit/docs/pipelines/configuring.lit            | 164 -------------
 lit/docs/pipelines/managing.lit               | 167 --------------
 lit/examples/attic/dockerhub.lit              |   2 +-
 lit/examples/git-triggered.lit                |   2 +-
 lit/examples/golang-lib.lit                   |   2 +-
 lit/examples/hello-world.lit                  |   2 +-
 lit/examples/hooks.lit                        |   2 +-
 lit/examples/java.lit                         |   2 +-
 lit/examples/manual-trigger.lit               |   2 +-
 lit/examples/nodejs.lit                       |   2 +-
 lit/examples/php.lit                          |   2 +-
 lit/examples/pipeline-vars.lit                |   2 +-
 lit/examples/rails.lit                        |   2 +-
 lit/examples/serial-job.lit                   |   2 +-
 lit/examples/set-pipelines.lit                |   2 +-
 lit/examples/task-inputs-outputs.lit          |   2 +-
 lit/examples/time-triggered.lit               |   2 +-
 lit/index.lit                                 |   2 +
 lit/references.lit                            |  19 ++
 lit/references/fly.lit                        |  58 +++++
 lit/references/fly/archive-pipeline.lit       |  17 ++
 lit/references/fly/completion.lit             |  19 ++
 lit/references/fly/delete-target.lit          |  19 ++
 lit/references/fly/destroy-pipeline.lit       |  14 ++
 lit/references/fly/edit-target.lit            |  13 ++
 lit/references/fly/expose-pipeline.lit        |  25 ++
 lit/references/fly/format-pipeline.lit        |  12 +
 lit/references/fly/get-pipeline.lit           |  16 ++
 lit/references/fly/hide-pipeline.lit          |  11 +
 .../fly}/instance-groups.lit                  |   0
 lit/references/fly/login.lit                  |  73 ++++++
 lit/references/fly/logout.lit                 |  18 ++
 lit/references/fly/order-pipeline.lit         |  20 ++
 lit/references/fly/pause-pipeline.lit         |  11 +
 lit/references/fly/pipelines.lit              |  11 +
 lit/references/fly/rename-pipeline.lit        |  10 +
 lit/references/fly/set-pipeline.lit           | 128 +++++++++++
 lit/references/fly/status.lit                 |  10 +
 lit/references/fly/sync.lit                   |  15 ++
 lit/references/fly/targets.lit                |  10 +
 lit/references/fly/unpause-pipeline.lit       |  10 +
 lit/references/fly/userinfo.lit               |   9 +
 lit/references/fly/validate-pipeline.lit      |  12 +
 lit/{docs => references}/pipelines.lit        |   5 -
 lit/{docs => references}/resource-types.lit   |   1 -
 .../resource-types/implementing.lit           |   0
 .../resource-types/managing.lit               |   0
 lit/users.lit                                 |   6 +
 lit/users/managing-pipelines.lit              |   4 +
 51 files changed, 587 insertions(+), 572 deletions(-)
 delete mode 100644 lit/docs/fly.lit
 delete mode 100644 lit/docs/pipelines/configuring.lit
 delete mode 100644 lit/docs/pipelines/managing.lit
 create mode 100644 lit/references.lit
 create mode 100644 lit/references/fly.lit
 create mode 100644 lit/references/fly/archive-pipeline.lit
 create mode 100644 lit/references/fly/completion.lit
 create mode 100644 lit/references/fly/delete-target.lit
 create mode 100644 lit/references/fly/destroy-pipeline.lit
 create mode 100644 lit/references/fly/edit-target.lit
 create mode 100644 lit/references/fly/expose-pipeline.lit
 create mode 100644 lit/references/fly/format-pipeline.lit
 create mode 100644 lit/references/fly/get-pipeline.lit
 create mode 100644 lit/references/fly/hide-pipeline.lit
 rename lit/{docs/pipelines => references/fly}/instance-groups.lit (100%)
 create mode 100644 lit/references/fly/login.lit
 create mode 100644 lit/references/fly/logout.lit
 create mode 100644 lit/references/fly/order-pipeline.lit
 create mode 100644 lit/references/fly/pause-pipeline.lit
 create mode 100644 lit/references/fly/pipelines.lit
 create mode 100644 lit/references/fly/rename-pipeline.lit
 create mode 100644 lit/references/fly/set-pipeline.lit
 create mode 100644 lit/references/fly/status.lit
 create mode 100644 lit/references/fly/sync.lit
 create mode 100644 lit/references/fly/targets.lit
 create mode 100644 lit/references/fly/unpause-pipeline.lit
 create mode 100644 lit/references/fly/userinfo.lit
 create mode 100644 lit/references/fly/validate-pipeline.lit
 rename lit/{docs => references}/pipelines.lit (97%)
 rename lit/{docs => references}/resource-types.lit (99%)
 rename lit/{docs => references}/resource-types/implementing.lit (100%)
 rename lit/{docs => references}/resource-types/managing.lit (100%)
 create mode 100644 lit/users.lit
 create mode 100644 lit/users/managing-pipelines.lit

diff --git a/lit/docs.lit b/lit/docs.lit
index 0d3c4db3..9aca0430 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -49,12 +49,9 @@ the "big picture" as the mental model sets in.
 
 \include-section{./docs/install.lit}
 \include-section{./docs/auth.lit}
-\include-section{./docs/fly.lit}
 \include-section{./docs/config.lit}
-\include-section{./docs/pipelines.lit}
 \include-section{./docs/vars.lit}
 \include-section{./docs/resources.lit}
-\include-section{./docs/resource-types.lit}
 \include-section{./docs/jobs.lit}
 \include-section{./docs/steps.lit}
 \include-section{./docs/tasks.lit}
diff --git a/lit/docs/fly.lit b/lit/docs/fly.lit
deleted file mode 100644
index 118c87f3..00000000
--- a/lit/docs/fly.lit
+++ /dev/null
@@ -1,217 +0,0 @@
-\title{\aux{The }\code{fly} CLI}{fly}{fly-cli}
-
-\use-plugin{concourse-docs}
-
-The first step to getting started with Concourse is to install the \code{fly}
-CLI tool. You can download \code{fly} from any Concourse installation. There
-are download links for common platforms in the bottom right hand corner of the
-main page.
-
-Throughout the Concourse documentation we'll stick to the long-form name of
-every command and flag. Once you've learned what the commands do, you may want
-to consult \code{fly -h} to learn the short forms.
-
-\table-of-contents
-
-\section{
-  \title{\code{fly login}}{fly-login}
-
-  The first thing you'll want to do is authenticate with your target. This is
-  done with the \reference{fly-login} command. This is also useful to save
-  targets under a more convenient alias, so you don't have to type out the URL
-  all the time:
-
-  The \code{login} command serves double duty: it authenticates with a given
-  endpoint, and saves it under a more convenient name. The name and token are
-  stored in \code{~/.flyrc} (though you shouldn't really edit the file
-  manually).
-
-  Concourse deployments can be occupied by multiple \reference{teams}{teams}.
-  To specify the team to which to log in, specify the \code{--team-name} or
-  \code{-n} flag. If not specified, this defaults to the \reference{main-team}.
-
-  So, to log in to a team \code{my-team} an endpoint served at
-  \code{https://ci.example.com} and save it as the more convenient name
-  \code{example}, you would run:
-
-  \codeblock{bash}{{{
-  $ fly --target example login --team-name my-team \
-      --concourse-url https://ci.example.com
-  }}}
-
-  The \code{login} command will see which authentication methods are available
-  for the specified team and prompt you to choose one. For basic auth, it will
-  ask your username and password and use them to acquire a token. For OAuth, it
-  will give you a link to click, and after you've gone through the OAuth flow
-  it will print an OAuth token on the page that you can then copy and
-  paste into the prompt.
-
-  Note that if no authentication methods are configured, \code{fly} will
-  acquire a token without any prompting. You can then use the alias like
-  normal.
-
-  In any case, a token is saved in your \code{~/.flyrc}, which will expire
-  after one day.
-
-  If your Concourse uses SSL but does not have a certificate signed by a
-  trusted CA, you can use the \code{--ca-cert} flag so that \code{fly} can
-  trust the connection, like so:
-
-  \codeblock{bash}{{
-  $ fly -t example login -c https://ci.example.com --ca-cert ./ca.crt
-  }}
-
-  This will read the value out of the file \code{./ca.crt} and save it into
-  \code{~/.flyrc} so you don't have to pass it on every \code{login}
-  invocation.
-
-  If your Concourse instance is protected by a proxy server requiring client
-  certificates, you can use \code{--client-cert} and \code{--client-key} to
-  point to where your certificate is stored. These paths will be stored in
-  \code{.flyrc} and the certificate will by attached to every request made to
-  that target.
-
-  \codeblock{bash}{{
-  $ fly -t example login -c https://ci-example.com \\
-      --client-cert ./client.pem \\
-      --client-key ./client.key
-  }}
-
-  After you've logged in you can use \code{--target example} (or \code{-t
-  example} for short) to run a command against the saved target \code{example}.
-  For example, \code{fly -t example builds} will list the last few builds on the
-  \code{example} Concourse instance.
-
-  The \code{-t} flag is intentionally stateless and must be explicitly added
-  to each command. This reduces the risk of accidentally running a command against the
-  wrong environment when you have multiple targets defined.
-}
-
-\section{
-  \title{\code{fly targets}}{fly-targets}
-
-  To see what targets are currently known to \code{fly}, run:
-
-  \codeblock{bash}{{
-  $ fly targets
-  }}
-
-  This will show each target's name, URL, and when its token expires.
-}
-
-\section{
-  \title{\code{fly status}}{fly-status}
-
-  To check your current authentication status with a given target, run:
-
-  \codeblock{bash}{{
-  $ fly -t example status
-  }}
-
-  This will let you know if the token has expired.
-}
-
-\section{
-  \title{\code{fly userinfo}}{fly-userinfo}
-
-  To check what user you're logged in as, as well as which teams you are
-  currently authenticated to and which roles within each team you have, run:
-
-  \codeblock{bash}{{
-  $ fly -t example userinfo
-  }}
-}
-
-\section{
-  \title{\code{fly logout}}{fly-logout}
-
-  To clear out your token for a given target, run:
-
-  \codeblock{bash}{{
-  $ fly -t example logout
-  }}
-
-  To clear out your token for \italic{all} targets, run:
-
-  \codeblock{bash}{{
-  $ fly logout -a
-  }}
-
-  Note: These two variations are mutually exclusive. If the target parameter
-  \code{-t} and all parameter \code{-a} are both specified, an error will
-  occur.
-}
-
-\section{
-  \title{\code{fly edit-target}}{fly-edit-target}
-
-  To modify a target's name, team, or URL, run:
-
-  \codeblock{bash}{{
-  $ fly -t example edit-target \\
-      --target-name new-name \\
-      --concourse-url https://ci.example.com \\
-      --team-name my-team
-  }}
-
-  Each flag is optional - only the specified flags will be changed.
-}
-
-\section{
-  \title{\code{fly delete-target}}{fly-delete-target}
-
-  When logging out just isn't enough, a target can be completely removed from
-  \code{~/.flyrc} by running:
-
-  \codeblock{bash}{{
-  $ fly -t example delete-target
-  }}
-
-  To delete \italic{all} targets, run:
-
-  \codeblock{bash}{{
-  $ fly delete-target -a
-  }}
-
-  Note: These two variations are mutually exclusive. If the target parameter
-  \code{-t} and all parameter \code{-a} are both specified, an error will
-  occur.
-}
-
-\section{
-  \title{\code{fly sync}}{fly-sync}
-
-  Occasionally we add additional features to \code{fly} or make changes to the
-  communication between it and Concourse's API server. To make sure you're
-  running the latest and greatest version that works with the Concourse you
-  are targeting we provide a command called \code{sync} that will update your
-  local \code{fly}. It can be used like so:
-
-  \codeblock{bash}{{
-  $ fly -t example sync
-  }}
-
-  The \code{fly} command will also warn you if it notices that your CLI version
-  is out of sync with the server.
-}
-
-\section{
-  \title{\code{fly completion}}{fly-completion}
-
-  Fly can output autocomplete configuration for some shells. For
-  example, you can add an entry to your \code{.bashrc} like this:
-
-  \codeblock{bash}{{
-  source <(fly completion --shell bash)
-  }}
-
-  or, using the \code{/etc/bash_completion.d} directory:
-
-  \codeblock{bash}{{
-  $ fly completion --shell bash > /etc/bash_completion.d/fly
-  }}
-
-  Note that, unlike other fly commands, this command does not interact with a
-  remote server so you do not need to provide the \code{-t} or \code{--target}
-  flag.
-}
diff --git a/lit/docs/pipelines/configuring.lit b/lit/docs/pipelines/configuring.lit
deleted file mode 100644
index c64ae095..00000000
--- a/lit/docs/pipelines/configuring.lit
+++ /dev/null
@@ -1,164 +0,0 @@
-\title{Setting Pipelines}{setting-pipelines}
-
-\use-plugin{concourse-docs}
-
-Pipelines are configured entirely via the \reference{fly-cli}. There is no GUI.
-
-\section{
-  \title{\code{fly set-pipeline}}{fly-set-pipeline}
-
-  \omit-children-from-table-of-contents
-
-  To submit a pipeline configuration to Concourse from a file on your local disk
-  you can use the \code{-c} or \code{--config} flag, like so:
-
-  \codeblock{bash}{{
-  $ fly -t example set-pipeline \\
-      --pipeline my-pipeline \\
-      --config pipeline.yml
-  }}
-
-  This will present a diff of the changes and ask you to confirm the changes.
-  If you accept then Concourse's pipeline configuration will switch to the
-  pipeline definition in the YAML file specified.
-
-  The \code{-c} or \code{--config} flag can also take in the value \code{-} to
-  indicate reading from \code{stdin}:
-
-  \codeblock{bash}{{
-  $ cat pipeline.yml | fly -t example set-pipeline \\
-      --pipeline my-pipeline \\
-      --config -
-  }}
-
-  Note that reading from \code{stdin} disables the confirmation prompt - the
-  pipeline will be set automatically.
-
-  \section{
-    \title{Providing static values for vars}{pipeline-static-vars}
-
-    The pipeline configuration can contain \reference{vars} which may be
-    \reference{static-vars}{replaced with static values} or
-    \reference{dynamic-vars}{loaded at runtime}. This allows for credentials
-    to be extracted from a pipeline config, making it safe to check in to a
-    public repository or pass around.
-
-    For example, if you have a \code{pipeline.yml} as follows:
-
-    \codeblock{yaml}{{
-    resources:
-    - name: private-repo
-      type: git
-      source:
-        uri: git@...
-        branch: master
-        private_key: ((private-repo-key))
-    }}
-
-    ...you could then configure this pipeline like so:
-
-    \codeblock{bash}{{
-    $ fly -t example set-pipeline \\
-        --pipeline my-pipeline \\
-        --config pipeline.yml \\
-        --var "private-repo-key=$(cat id_rsa)"
-    }}
-
-    Or, if you had a \code{vars.yml} as follows:
-
-    \codeblock{yaml}{{
-    private-repo-key: |
-      -----BEGIN RSA PRIVATE KEY-----
-      ...
-      -----END RSA PRIVATE KEY-----
-    }}
-
-    ...you could configure it like so:
-
-    \codeblock{bash}{{
-    $ fly -t example set-pipeline \\
-        --pipeline my-pipeline \\
-        --config pipeline.yml \\
-        --load-vars-from vars.yml
-    }}
-
-    You can use nested fields in your \code{pipeline.yml} as follows:
-    \codeblock{yaml}{{
-    resources:
-    - name: private-repo
-      type: git
-      source:
-        uri: git@((repo.uri))
-        branch: ((repo.branch))
-        private_key: (("github.com".private-repo-key))
-    }}
-
-    ...you could configure it by \code{--load-vars-from} with a \code{vars.yml} as follows:
-
-    \codeblock{yaml}{{
-    repo:
-      uri: github.com/...
-      branch: master
-    github.com:
-      private-repo-key: |
-        -----BEGIN RSA PRIVATE KEY-----
-        ...
-        -----END RSA PRIVATE KEY-----
-    }}
-
-    ...or you could also configure it by passing the vars as flags:
-
-    \codeblock{bash}{{
-    $ fly -t example set-pipeline \\
-        --pipeline my-pipeline \\
-        --config pipeline.yml \\
-        --var "repo.uri=github.com" \\
-        --var "repo.branch=master" \\
-        --var "\\"github.com\\".private-repo-key=$(cat id_rsa)"
-    }}
-
-    When configuring a pipeline, any vars not provided statically will be left
-    to resolve \reference{dynamic-vars}{at runtime}. To check that all vars are
-    resolveable, you can pass the \code{--check-creds} flag:
-
-    \codeblock{bash}{{
-    $ fly -t example set-pipeline \\
-        --pipeline my-pipeline \\
-        --config pipeline.yml \\
-        --load-vars-from vars.yml \\
-        --check-creds
-    }}
-
-    This will fill in all statically-provided vars and then attempt to resolve
-    all remanining vars server-side. If any fail to resolve, configuring the
-    pipeline will fail.
-  }
-}
-
-\section{
-  \title{\code{fly validate-pipeline}}{fly-validate-pipeline}
-
-  To validate a local pipeline configuration without submitting it to Concourse,
-  run \code{validate-pipeline}:
-
-  \codeblock{bash}{{
-  $ fly validate-pipeline --config pipeline.yml
-  }}
-
-  By default, pipeline errors will cause \code{validate-pipeline} to fail, but
-  warnings won't. To fail on both errors and warnings, pass the `--strict` flag.
-}
-
-\section{
-  \title{\code{fly format-pipeline}}{fly-format-pipeline}
-
-  To format a pipeline config in a "canonical" form (i.e. keys are in normal
-  order, with \code{name} first for example), run:
-
-  \codeblock{bash}{{
-  $ fly format-pipeline --config pipeline.yml
-  }}
-
-  This will print the formatted pipeline config to \code{stdout}. To update the
-  file in-place, pass \code{--write/-w}.
-}
diff --git a/lit/docs/pipelines/managing.lit b/lit/docs/pipelines/managing.lit
deleted file mode 100644
index e497e744..00000000
--- a/lit/docs/pipelines/managing.lit
+++ /dev/null
@@ -1,167 +0,0 @@
-\title{Managing Pipelines}{managing-pipelines}
-
-\use-plugin{concourse-docs}
-
-\section{
-  \title{\code{fly pipelines}}{fly-pipelines}
-
-  To list the currently-configured pipelines and their paused state, run:
-
-  \codeblock{bash}{{
-  $ fly -t example pipelines
-  }}
-
-  By default, archived pipelines are not included in the output of this command.
-  To view archived pipelines, provide \code{--include-archived} flag.
-}
-
-\section{
-  \title{\code{fly rename-pipeline}}{fly-rename-pipeline}
-
-  To rename a pipeline, run:
-
-  \codeblock{bash}{{
-  $ fly -t example rename-pipeline \\
-      --old-name my-pipeline \\
-      --new-name my-cool-pipeline
-  }}
-}
-
-\section{
-  \title{\code{fly pause-pipeline}}{fly-pause-pipeline}
-
-  To pause a pipeline, run:
-
-  \codeblock{bash}{{
-  $ fly -t example pause-pipeline --pipeline my-pipeline
-  }}
-
-  This will prevent jobs from being scheduled and stop the periodic checking
-  for new versions of resources. Builds that are in-flight will still finish.
-}
-
-\section{
-  \title{\code{fly unpause-pipeline}}{fly-unpause-pipeline}
-
-  To unpause a pipeline, run:
-
-  \codeblock{bash}{{
-  $ fly -t example unpause-pipeline --pipeline my-pipeline
-  }}
-
-  This will resume job scheduling and resource checking.
-}
-
-\section{
-  \title{\code{fly expose-pipeline}}{fly-expose-pipeline}
-
-  By default, newly configured pipelines are only visible to the pipeline's
-  team. To make a pipeline viewable by other teams and unauthenticated users,
-  run:
-
-  \codeblock{bash}{{
-  $ fly -t example expose-pipeline --pipeline my-pipeline
-  }}
-
-  This feature is useful if you're using Concourse for an open source project
-  and you'd like your community to be able to see into your build pipeline.
-
-  To undo this change, see \reference{fly-hide-pipeline}.
-
-  Exposing a pipeline reveals basically everything except for build output and
-  resource metadata.
-
-  To expose a resource's metadata, \reference{schema.resource.public} must be set to
-  \code{true}.
-
-  To expose a job's build output, \reference{schema.job.public} must be set to
-  \code{true}. This will also reveal resource metadata for any
-  \reference{get-step} or \reference{put-step}s in the build output.
-}
-
-\section{
-  \title{\code{fly hide-pipeline}}{fly-hide-pipeline}
-
-  If you realize that you've made a terrible mistake in
-  \reference{fly-expose-pipeline}{exposing your pipeline}, you can run:
-
-  \codeblock{bash}{{
-  $ fly -t example hide-pipeline --pipeline my-pipeline
-  }}
-
-  If you're panicking you can run the command's short form, \code{hp}, instead.
-}
-
-\section{
-  \title{\code{fly get-pipeline}}{fly-get-pipeline}
-
-  Fly can be used to fetch and update the configuration for your pipelines. This
-  is achieved by using the \reference{fly-get-pipeline} and
-  \reference{fly-set-pipeline} commands. For example, to fetch the current
-  configuration of your \code{my-pipeline} Concourse pipeline and print it on
-  \code{STDOUT} run the following:
-
-  \codeblock{bash}{{
-  $ fly -t example get-pipeline --pipeline my-pipeline
-  }}
-
-  To get JSON instead of YAML you can use the \code{-j} or \code{--json}
-  argument. This can be useful when inspecting your config with
-  \link{jq}{http://stedolan.github.io/jq/}.
-}
-
-\section{
-  \title{\code{fly destroy-pipeline}}{fly-destroy-pipeline}
-
-  Every now and then you just don't want a pipeline to be around anymore.
-  Running \code{fly destroy-pipeline} will stop the pipeline activity and remove
-  all data collected by the pipeline, including build history and collected
-  versions.
-
-  For example, to destroy the \code{my-pipeline} pipeline, you would run:
-
-  \codeblock{bash}{{
-  $ fly -t example destroy-pipeline --pipeline my-pipeline
-  }}
-}
-
-\section{
-  \title{\code{fly order-pipelines}}{fly-order-pipelines}
-
-  To configure the ordering of pipelines, run:
-
-  \codeblock{bash}{{
-  $ fly -t example order-pipelines \\
-      --pipeline pipeline-1 \\
-      --pipeline pipeline-2 \\
-      --pipeline pipeline-3
-  }}
-
-  Note that this command only ensures that the given pipelines are in the given
-  order. If there are other pipelines that you haven't included in the command,
-  they may appear in-between, before, or after the given set.
-
-  \warn{
-    If you want to reorder instanced pipelines within an individual instance
-    group, you should use the \reference{fly-order-instanced-pipelines} command.
-  }
-}
-
-\section{
-    \title{\code{fly archive-pipeline}}{fly-archive-pipeline}
-
-    A pipeline can be archived via fly. This means that the pipeline will be paused
-    and hidden from the web UI. The pipeline config will be deleted (so any secrets or
-    interpolated \reference{vars} will be removed) while the build logs will be retained.
-
-    \codeblock{bash}{{
-    $ fly -t example archive-pipeline -p pipeline-1
-    }}
-
-    To unarchive a pipeline, simply set the pipeline again with the same name
-    using \reference{fly-set-pipeline}. If a job in the new pipeline has the same name
-    as a job in the archived pipeline, the old build logs for that job will be restored.
-
-    Note that because the config is deleted, \reference{fly-get-pipeline} will no
-    longer work for archived pipelines.
-}
diff --git a/lit/examples/attic/dockerhub.lit b/lit/examples/attic/dockerhub.lit
index 7270bcd3..ccae7d52 100644
--- a/lit/examples/attic/dockerhub.lit
+++ b/lit/examples/attic/dockerhub.lit
@@ -56,7 +56,7 @@ jobs:
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/git-triggered.lit b/lit/examples/git-triggered.lit
index 7d581b71..b15edf52 100644
--- a/lit/examples/git-triggered.lit
+++ b/lit/examples/git-triggered.lit
@@ -13,7 +13,7 @@ The \resource{git} can be used to trigger a job.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{resources}
diff --git a/lit/examples/golang-lib.lit b/lit/examples/golang-lib.lit
index 091e34f2..cfc3fec0 100644
--- a/lit/examples/golang-lib.lit
+++ b/lit/examples/golang-lib.lit
@@ -22,7 +22,7 @@ will ensure consistency between the image versions fetched by the
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/hello-world.lit b/lit/examples/hello-world.lit
index 55789aca..cd7bb250 100644
--- a/lit/examples/hello-world.lit
+++ b/lit/examples/hello-world.lit
@@ -17,7 +17,7 @@ Also, due to the fact that there are minimal external factors (\reference{resour
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/hooks.lit b/lit/examples/hooks.lit
index bce2a23a..674fd0e1 100644
--- a/lit/examples/hooks.lit
+++ b/lit/examples/hooks.lit
@@ -15,7 +15,7 @@ job.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{schema.job.on_success}
diff --git a/lit/examples/java.lit b/lit/examples/java.lit
index 59cbb125..8fc08c0f 100644
--- a/lit/examples/java.lit
+++ b/lit/examples/java.lit
@@ -13,7 +13,7 @@ You can run the tests for a Java application.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/manual-trigger.lit b/lit/examples/manual-trigger.lit
index 4333b236..6cf1ae8b 100644
--- a/lit/examples/manual-trigger.lit
+++ b/lit/examples/manual-trigger.lit
@@ -13,7 +13,7 @@ A job can be triggered by a resource. After it's complete, the next job can run
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{resources}
diff --git a/lit/examples/nodejs.lit b/lit/examples/nodejs.lit
index 520caac1..aaf3da9c 100644
--- a/lit/examples/nodejs.lit
+++ b/lit/examples/nodejs.lit
@@ -13,7 +13,7 @@ You can run the tests for a Nodejs application.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/php.lit b/lit/examples/php.lit
index 74b04b25..b28e7201 100644
--- a/lit/examples/php.lit
+++ b/lit/examples/php.lit
@@ -13,7 +13,7 @@ You can run the tests for a PHP application.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/pipeline-vars.lit b/lit/examples/pipeline-vars.lit
index 2f71b8e7..23fee38b 100644
--- a/lit/examples/pipeline-vars.lit
+++ b/lit/examples/pipeline-vars.lit
@@ -23,7 +23,7 @@ hello: HAL
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/rails.lit b/lit/examples/rails.lit
index 96fc9d2b..e7e463a4 100644
--- a/lit/examples/rails.lit
+++ b/lit/examples/rails.lit
@@ -13,7 +13,7 @@ You can run the tests for a Rails that requires a specific version of ruby and r
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/serial-job.lit b/lit/examples/serial-job.lit
index 83138840..496cd393 100644
--- a/lit/examples/serial-job.lit
+++ b/lit/examples/serial-job.lit
@@ -17,7 +17,7 @@ You can also set the \reference{schema.job.max_in_flight} value to 1 to disable
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/set-pipelines.lit b/lit/examples/set-pipelines.lit
index 0f3a3ffa..c2fefbf6 100644
--- a/lit/examples/set-pipelines.lit
+++ b/lit/examples/set-pipelines.lit
@@ -13,7 +13,7 @@ You can set a static set of pipelines from another pipeline on the same team.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{jobs}
diff --git a/lit/examples/task-inputs-outputs.lit b/lit/examples/task-inputs-outputs.lit
index 62a1c417..075a10d8 100644
--- a/lit/examples/task-inputs-outputs.lit
+++ b/lit/examples/task-inputs-outputs.lit
@@ -19,7 +19,7 @@ These constructs give you the ability to design a pipeline that can process arti
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{schema.task-config.outputs}
diff --git a/lit/examples/time-triggered.lit b/lit/examples/time-triggered.lit
index 0226eb94..7d0655d8 100644
--- a/lit/examples/time-triggered.lit
+++ b/lit/examples/time-triggered.lit
@@ -13,7 +13,7 @@ The \resource{time} can be used to trigger a job.
 }
 
 \section{
-	\title{References}{references}
+	\title{See also}
 
 	\list{
 		\reference{resources}
diff --git a/lit/index.lit b/lit/index.lit
index af4999d2..75fadcaf 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -196,7 +196,9 @@
 \split-sections
 
 \include-section{./beginners.lit}
+\include-section{./users.lit}
 \include-section{./docs.lit}
 \include-section{./examples.lit}
 \include-section{./project.lit}
 \include-section{./ecosystem.lit}
+\include-section{./references.lit}
diff --git a/lit/references.lit b/lit/references.lit
new file mode 100644
index 00000000..27bc52d6
--- /dev/null
+++ b/lit/references.lit
@@ -0,0 +1,19 @@
+\title{References}{references}
+\use-plugin{concourse-docs}
+\split-sections
+
+This page is a collection of all references.
+
+
+{-
+Contains a reference of:
+
+* fly CLI commands
+* Syntax and format of the Concourse YAML file
+* API
+* Resource types
+-}
+
+\include-section{./references/fly.lit}
+\include-section{./references/resource-types.lit}
+\include-section{./references/pipelines.lit}
\ No newline at end of file
diff --git a/lit/references/fly.lit b/lit/references/fly.lit
new file mode 100644
index 00000000..5ec0e678
--- /dev/null
+++ b/lit/references/fly.lit
@@ -0,0 +1,58 @@
+\title{\aux{The }\code{fly} CLI}{fly}{fly-cli}
+\use-plugin{concourse-docs}
+\split-sections
+
+The first step to getting started with Concourse is to install the \code{fly}
+CLI tool. You can download \code{fly} from any Concourse installation. There
+are download links for common platforms in the bottom right hand corner of the
+main page.
+
+Throughout the Concourse documentation we'll stick to the long-form name of
+every command and flag. Once you've learned what the commands do, you may want
+to consult \code{fly -h} to learn the short forms.
+
+\section{
+  \title{Global options}
+
+  {-
+  tomschr: maybe this could be a bit more verbose. For example,
+  some code examples to show the effect.
+  -}
+
+  \definitions{
+    \definition{\code{-t}, \code{--target=}}{Concourse target name}
+  }{
+    \definition{\code{--version}}{Print the version of Fly and exit}
+  }{
+    \definition{\code{--verbose}}{Print API requests and responses}
+  }{
+    \definition{\code{--print-table-headers}}{Print table headers even for redirected output}
+  }
+}
+
+
+\table-of-contents
+
+\include-section{fly/archive-pipeline.lit}
+\include-section{fly/completion.lit}
+\include-section{fly/delete-target.lit}
+\include-section{fly/destroy-pipeline.lit}
+\include-section{fly/edit-target.lit}
+\include-section{fly/expose-pipeline.lit}
+\include-section{fly/format-pipeline.lit}
+\include-section{fly/get-pipeline.lit}
+\include-section{fly/hide-pipeline.lit}
+\include-section{fly/login.lit}
+\include-section{fly/logout.lit}
+\include-section{fly/instance-groups.lit}
+\include-section{fly/order-pipeline.lit}
+\include-section{fly/pause-pipeline.lit}
+\include-section{fly/pipelines.lit}
+\include-section{fly/rename-pipeline.lit}
+\include-section{fly/set-pipeline.lit}
+\include-section{fly/status.lit}
+\include-section{fly/sync.lit}
+\include-section{fly/targets.lit}
+\include-section{fly/unpause-pipeline.lit}
+\include-section{fly/userinfo.lit}
+\include-section{fly/validate-pipeline.lit}
diff --git a/lit/references/fly/archive-pipeline.lit b/lit/references/fly/archive-pipeline.lit
new file mode 100644
index 00000000..5461c050
--- /dev/null
+++ b/lit/references/fly/archive-pipeline.lit
@@ -0,0 +1,17 @@
+\title{\code{fly archive-pipeline}}{fly-archive-pipeline}
+\use-plugin{concourse-docs}
+
+A pipeline can be archived via fly. This means that the pipeline will be paused
+and hidden from the web UI. The pipeline config will be deleted (so any secrets or
+interpolated \reference{vars} will be removed) while the build logs will be retained.
+
+\codeblock{bash}{{
+$ fly -t example archive-pipeline -p pipeline-1
+}}
+
+To unarchive a pipeline, simply set the pipeline again with the same name
+using \reference{fly-set-pipeline}. If a job in the new pipeline has the same name
+as a job in the archived pipeline, the old build logs for that job will be restored.
+
+Note that because the config is deleted, \reference{fly-get-pipeline} will no
+longer work for archived pipelines.
diff --git a/lit/references/fly/completion.lit b/lit/references/fly/completion.lit
new file mode 100644
index 00000000..9fd158b3
--- /dev/null
+++ b/lit/references/fly/completion.lit
@@ -0,0 +1,19 @@
+\title{\code{fly completion}}{fly-completion}
+\use-plugin{concourse-docs}
+
+Fly can output autocomplete configuration for some shells. For
+example, you can add an entry to your \code{.bashrc} like this:
+
+\codeblock{bash}{{
+source <(fly completion --shell bash)
+}}
+
+or, using the \code{/etc/bash_completion.d} directory:
+
+\codeblock{bash}{{
+$ fly completion --shell bash > /etc/bash_completion.d/fly
+}}
+
+Note that, unlike other fly commands, this command does not interact with a
+remote server so you do not need to provide the \code{-t} or \code{--target}
+flag.
diff --git a/lit/references/fly/delete-target.lit b/lit/references/fly/delete-target.lit
new file mode 100644
index 00000000..6ae5a964
--- /dev/null
+++ b/lit/references/fly/delete-target.lit
@@ -0,0 +1,19 @@
+\title{\code{fly delete-target}}{fly-delete-target}
+\use-plugin{concourse-docs}
+
+When logging out just isn't enough, a target can be completely removed from
+\code{~/.flyrc} by running:
+
+\codeblock{bash}{{
+$ fly -t example delete-target
+}}
+
+To delete \italic{all} targets, run:
+
+\codeblock{bash}{{
+$ fly delete-target -a
+}}
+
+Note: These two variations are mutually exclusive. If the target parameter
+\code{-t} and all parameter \code{-a} are both specified, an error will
+occur.
diff --git a/lit/references/fly/destroy-pipeline.lit b/lit/references/fly/destroy-pipeline.lit
new file mode 100644
index 00000000..70602a20
--- /dev/null
+++ b/lit/references/fly/destroy-pipeline.lit
@@ -0,0 +1,14 @@
+\title{\code{fly destroy-pipeline}}{fly-destroy-pipeline}
+\use-plugin{concourse-docs}
+
+
+Every now and then you just don't want a pipeline to be around anymore.
+Running \code{fly destroy-pipeline} will stop the pipeline activity and remove
+all data collected by the pipeline, including build history and collected
+versions.
+
+For example, to destroy the \code{my-pipeline} pipeline, you would run:
+
+\codeblock{bash}{{
+$ fly -t example destroy-pipeline --pipeline my-pipeline
+}}
\ No newline at end of file
diff --git a/lit/references/fly/edit-target.lit b/lit/references/fly/edit-target.lit
new file mode 100644
index 00000000..afe7b61a
--- /dev/null
+++ b/lit/references/fly/edit-target.lit
@@ -0,0 +1,13 @@
+\title{\code{fly edit-target}}{fly-edit-target}
+\use-plugin{concourse-docs}
+
+To modify a target's name, team, or URL, run:
+
+\codeblock{bash}{{
+$ fly -t example edit-target \\
+    --target-name new-name \\
+    --concourse-url https://ci.example.com \\
+    --team-name my-team
+}}
+
+Each flag is optional - only the specified flags will be changed.
diff --git a/lit/references/fly/expose-pipeline.lit b/lit/references/fly/expose-pipeline.lit
new file mode 100644
index 00000000..b9b726b7
--- /dev/null
+++ b/lit/references/fly/expose-pipeline.lit
@@ -0,0 +1,25 @@
+\title{\code{fly expose-pipeline}}{fly-expose-pipeline}
+\use-plugin{concourse-docs}
+
+By default, newly configured pipelines are only visible to the pipeline's
+team. To make a pipeline viewable by other teams and unauthenticated users,
+run:
+
+\codeblock{bash}{{
+$ fly -t example expose-pipeline --pipeline my-pipeline
+}}
+
+This feature is useful if you're using Concourse for an open source project
+and you'd like your community to be able to see into your build pipeline.
+
+To undo this change, see \reference{fly-hide-pipeline}.
+
+Exposing a pipeline reveals basically everything except for build output and
+resource metadata.
+
+To expose a resource's metadata, \reference{schema.resource.public} must be set to
+\code{true}.
+
+To expose a job's build output, \reference{schema.job.public} must be set to
+\code{true}. This will also reveal resource metadata for any
+\reference{get-step} or \reference{put-step}s in the build output.
diff --git a/lit/references/fly/format-pipeline.lit b/lit/references/fly/format-pipeline.lit
new file mode 100644
index 00000000..a63e633b
--- /dev/null
+++ b/lit/references/fly/format-pipeline.lit
@@ -0,0 +1,12 @@
+\title{\code{fly format-pipeline}}{fly-format-pipeline}
+\use-plugin{concourse-docs}
+
+To format a pipeline config in a "canonical" form (i.e. keys are in normal
+order, with \code{name} first for example), run:
+
+\codeblock{bash}{{
+$ fly format-pipeline --config pipeline.yml
+}}
+
+This will print the formatted pipeline config to \code{stdout}. To update the
+file in-place, pass \code{--write/-w}.
\ No newline at end of file
diff --git a/lit/references/fly/get-pipeline.lit b/lit/references/fly/get-pipeline.lit
new file mode 100644
index 00000000..801d4b92
--- /dev/null
+++ b/lit/references/fly/get-pipeline.lit
@@ -0,0 +1,16 @@
+\title{\code{fly get-pipeline}}{fly-get-pipeline}
+\use-plugin{concourse-docs}
+
+Fly can be used to fetch and update the configuration for your pipelines. This
+is achieved by using the \reference{fly-get-pipeline} and
+\reference{fly-set-pipeline} commands. For example, to fetch the current
+configuration of your \code{my-pipeline} Concourse pipeline and print it on
+\code{STDOUT} run the following:
+
+\codeblock{bash}{{
+$ fly -t example get-pipeline --pipeline my-pipeline
+}}
+
+To get JSON instead of YAML you can use the \code{-j} or \code{--json}
+argument. This can be useful when inspecting your config with
+\link{jq}{http://stedolan.github.io/jq/}.
diff --git a/lit/references/fly/hide-pipeline.lit b/lit/references/fly/hide-pipeline.lit
new file mode 100644
index 00000000..27298e69
--- /dev/null
+++ b/lit/references/fly/hide-pipeline.lit
@@ -0,0 +1,11 @@
+\title{\code{fly hide-pipeline}}{fly-hide-pipeline}
+\use-plugin{concourse-docs}
+
+If you realize that you've made a terrible mistake in
+\reference{fly-expose-pipeline}{exposing your pipeline}, you can run:
+
+\codeblock{bash}{{
+$ fly -t example hide-pipeline --pipeline my-pipeline
+}}
+
+If you're panicking you can run the command's short form, \code{hp}, instead.
diff --git a/lit/docs/pipelines/instance-groups.lit b/lit/references/fly/instance-groups.lit
similarity index 100%
rename from lit/docs/pipelines/instance-groups.lit
rename to lit/references/fly/instance-groups.lit
diff --git a/lit/references/fly/login.lit b/lit/references/fly/login.lit
new file mode 100644
index 00000000..2490d4b9
--- /dev/null
+++ b/lit/references/fly/login.lit
@@ -0,0 +1,73 @@
+\title{\code{fly login}}{fly-login}
+\use-plugin{concourse-docs}
+
+
+The first thing you'll want to do is authenticate with your target. This is
+done with the \reference{fly-login} command. This is also useful to save
+targets under a more convenient alias, so you don't have to type out the URL
+all the time:
+
+The \code{login} command serves double duty: it authenticates with a given
+endpoint, and saves it under a more convenient name. The name and token are
+stored in \code{~/.flyrc} (though you shouldn't really edit the file
+manually).
+
+Concourse deployments can be occupied by multiple \reference{teams}{teams}.
+To specify the team to which to log in, specify the \code{--team-name} or
+\code{-n} flag. If not specified, this defaults to the \reference{main-team}.
+
+So, to log in to a team \code{my-team} an endpoint served at
+\code{https://ci.example.com} and save it as the more convenient name
+\code{example}, you would run:
+
+  \codeblock{bash}{{{
+  $ fly --target example login --team-name my-team \
+     --concourse-url https://ci.example.com
+  }}}
+
+The \code{login} command will see which authentication methods are available
+for the specified team and prompt you to choose one. For basic auth, it will
+ask your username and password and use them to acquire a token. For OAuth, it
+will give you a link to click, and after you've gone through the OAuth flow
+it will print an OAuth token on the page that you can then copy and
+paste into the prompt.
+
+Note that if no authentication methods are configured, \code{fly} will
+acquire a token without any prompting. You can then use the alias like
+normal.
+
+In any case, a token is saved in your \code{~/.flyrc}, which will expire
+after one day.
+
+If your Concourse uses SSL but does not have a certificate signed by a
+trusted CA, you can use the \code{--ca-cert} flag so that \code{fly} can
+trust the connection, like so:
+
+\codeblock{bash}{{
+$ fly -t example login -c https://ci.example.com --ca-cert ./ca.crt
+}}
+
+This will read the value out of the file \code{./ca.crt} and save it into
+\code{~/.flyrc} so you don't have to pass it on every \code{login}
+invocation.
+
+If your Concourse instance is protected by a proxy server requiring client
+certificates, you can use \code{--client-cert} and \code{--client-key} to
+point to where your certificate is stored. These paths will be stored in
+\code{.flyrc} and the certificate will by attached to every request made to
+that target.
+
+\codeblock{bash}{{
+$ fly -t example login -c https://ci-example.com \\
+    --client-cert ./client.pem \\
+    --client-key ./client.key
+}}
+
+After you've logged in you can use \code{--target example} (or \code{-t
+example} for short) to run a command against the saved target \code{example}.
+For example, \code{fly -t example builds} will list the last few builds on the
+\code{example} Concourse instance.
+
+The \code{-t} flag is intentionally stateless and must be explicitly added
+to each command. This reduces the risk of accidentally running a command against the
+wrong environment when you have multiple targets defined.
diff --git a/lit/references/fly/logout.lit b/lit/references/fly/logout.lit
new file mode 100644
index 00000000..0c1c49d9
--- /dev/null
+++ b/lit/references/fly/logout.lit
@@ -0,0 +1,18 @@
+\title{\code{fly logout}}{fly-logout}
+\use-plugin{concourse-docs}
+
+To clear out your token for a given target, run:
+
+\codeblock{bash}{{
+$ fly -t example logout
+}}
+
+To clear out your token for \italic{all} targets, run:
+
+\codeblock{bash}{{
+$ fly logout -a
+}}
+
+Note: These two variations are mutually exclusive. If the target parameter
+\code{-t} and all parameter \code{-a} are both specified, an error will
+occur.
diff --git a/lit/references/fly/order-pipeline.lit b/lit/references/fly/order-pipeline.lit
new file mode 100644
index 00000000..ad10a772
--- /dev/null
+++ b/lit/references/fly/order-pipeline.lit
@@ -0,0 +1,20 @@
+\title{\code{fly order-pipelines}}{fly-order-pipelines}
+\use-plugin{concourse-docs}
+
+To configure the ordering of pipelines, run:
+
+\codeblock{bash}{{
+$ fly -t example order-pipelines \\
+    --pipeline pipeline-1 \\
+    --pipeline pipeline-2 \\
+    --pipeline pipeline-3
+}}
+
+Note that this command only ensures that the given pipelines are in the given
+order. If there are other pipelines that you haven't included in the command,
+they may appear in-between, before, or after the given set.
+
+\warn{
+If you want to reorder instanced pipelines within an individual instance
+group, you should use the \reference{fly-order-instanced-pipelines} command.
+}
diff --git a/lit/references/fly/pause-pipeline.lit b/lit/references/fly/pause-pipeline.lit
new file mode 100644
index 00000000..f55098b3
--- /dev/null
+++ b/lit/references/fly/pause-pipeline.lit
@@ -0,0 +1,11 @@
+\title{\code{fly pause-pipeline}}{fly-pause-pipeline}
+\use-plugin{concourse-docs}
+
+To pause a pipeline, run:
+
+\codeblock{bash}{{
+$ fly -t example pause-pipeline --pipeline my-pipeline
+}}
+
+This will prevent jobs from being scheduled and stop the periodic checking
+for new versions of resources. Builds that are in-flight will still finish.
diff --git a/lit/references/fly/pipelines.lit b/lit/references/fly/pipelines.lit
new file mode 100644
index 00000000..af9da249
--- /dev/null
+++ b/lit/references/fly/pipelines.lit
@@ -0,0 +1,11 @@
+\title{\code{fly pipelines}}{fly-pipelines}
+\use-plugin{concourse-docs}
+
+To list the currently-configured pipelines and their paused state, run:
+
+\codeblock{bash}{{
+$ fly -t example pipelines
+}}
+
+By default, archived pipelines are not included in the output of this command.
+To view archived pipelines, provide \code{--include-archived} flag.
diff --git a/lit/references/fly/rename-pipeline.lit b/lit/references/fly/rename-pipeline.lit
new file mode 100644
index 00000000..c7ae55bc
--- /dev/null
+++ b/lit/references/fly/rename-pipeline.lit
@@ -0,0 +1,10 @@
+\title{\code{fly rename-pipeline}}{fly-rename-pipeline}
+\use-plugin{concourse-docs}
+
+To rename a pipeline, run:
+
+\codeblock{bash}{{
+$ fly -t example rename-pipeline \\
+    --old-name my-pipeline \\
+    --new-name my-cool-pipeline
+}}
\ No newline at end of file
diff --git a/lit/references/fly/set-pipeline.lit b/lit/references/fly/set-pipeline.lit
new file mode 100644
index 00000000..ccad0e45
--- /dev/null
+++ b/lit/references/fly/set-pipeline.lit
@@ -0,0 +1,128 @@
+\title{\code{fly set-pipeline}}{fly-set-pipeline}
+\use-plugin{concourse-docs}
+\omit-children-from-table-of-contents
+
+To submit a pipeline configuration to Concourse from a file on your local disk
+you can use the \code{-c} or \code{--config} flag, like so:
+
+\codeblock{bash}{{
+$ fly -t example set-pipeline \\
+    --pipeline my-pipeline \\
+    --config pipeline.yml
+}}
+
+This will present a diff of the changes and ask you to confirm the changes.
+If you accept then Concourse's pipeline configuration will switch to the
+pipeline definition in the YAML file specified.
+
+The \code{-c} or \code{--config} flag can also take in the value \code{-} to
+indicate reading from \code{stdin}:
+
+\codeblock{bash}{{
+$ cat pipeline.yml | fly -t example set-pipeline \\
+    --pipeline my-pipeline \\
+    --config -
+}}
+
+Note that reading from \code{stdin} disables the confirmation prompt - the
+pipeline will be set automatically.
+
+\section{
+\title{Providing static values for vars}{pipeline-static-vars}
+
+The pipeline configuration can contain \reference{vars} which may be
+\reference{static-vars}{replaced with static values} or
+\reference{dynamic-vars}{loaded at runtime}. This allows for credentials
+to be extracted from a pipeline config, making it safe to check in to a
+public repository or pass around.
+
+For example, if you have a \code{pipeline.yml} as follows:
+
+\codeblock{yaml}{{
+resources:
+- name: private-repo
+    type: git
+    source:
+    uri: git@...
+    branch: master
+    private_key: ((private-repo-key))
+}}
+
+...you could then configure this pipeline like so:
+
+\codeblock{bash}{{
+$ fly -t example set-pipeline \\
+    --pipeline my-pipeline \\
+    --config pipeline.yml \\
+    --var "private-repo-key=$(cat id_rsa)"
+}}
+
+Or, if you had a \code{vars.yml} as follows:
+
+\codeblock{yaml}{{
+private-repo-key: |
+    -----BEGIN RSA PRIVATE KEY-----
+    ...
+    -----END RSA PRIVATE KEY-----
+}}
+
+...you could configure it like so:
+
+\codeblock{bash}{{
+$ fly -t example set-pipeline \\
+    --pipeline my-pipeline \\
+    --config pipeline.yml \\
+    --load-vars-from vars.yml
+}}
+
+You can use nested fields in your \code{pipeline.yml} as follows:
+\codeblock{yaml}{{
+resources:
+- name: private-repo
+    type: git
+    source:
+    uri: git@((repo.uri))
+    branch: ((repo.branch))
+    private_key: (("github.com".private-repo-key))
+}}
+
+...you could configure it by \code{--load-vars-from} with a \code{vars.yml} as follows:
+
+\codeblock{yaml}{{
+repo:
+    uri: github.com/...
+    branch: master
+github.com:
+    private-repo-key: |
+    -----BEGIN RSA PRIVATE KEY-----
+    ...
+    -----END RSA PRIVATE KEY-----
+}}
+
+...or you could also configure it by passing the vars as flags:
+
+\codeblock{bash}{{
+$ fly -t example set-pipeline \\
+    --pipeline my-pipeline \\
+    --config pipeline.yml \\
+    --var "repo.uri=github.com" \\
+    --var "repo.branch=master" \\
+    --var "\\"github.com\\".private-repo-key=$(cat id_rsa)"
+}}
+
+When configuring a pipeline, any vars not provided statically will be left
+to resolve \reference{dynamic-vars}{at runtime}. To check that all vars are
+resolveable, you can pass the \code{--check-creds} flag:
+
+\codeblock{bash}{{
+$ fly -t example set-pipeline \\
+    --pipeline my-pipeline \\
+    --config pipeline.yml \\
+    --load-vars-from vars.yml \\
+    --check-creds
+}}
+
+This will fill in all statically-provided vars and then attempt to resolve
+all remanining vars server-side. If any fail to resolve, configuring the
+pipeline will fail.
+}
diff --git a/lit/references/fly/status.lit b/lit/references/fly/status.lit
new file mode 100644
index 00000000..7f06b140
--- /dev/null
+++ b/lit/references/fly/status.lit
@@ -0,0 +1,10 @@
+\title{\code{fly status}}{fly-status}
+\use-plugin{concourse-docs}
+
+To check your current authentication status with a given target, run:
+
+\codeblock{bash}{{
+$ fly -t example status
+}}
+
+This will let you know if the token has expired.
\ No newline at end of file
diff --git a/lit/references/fly/sync.lit b/lit/references/fly/sync.lit
new file mode 100644
index 00000000..07f602a0
--- /dev/null
+++ b/lit/references/fly/sync.lit
@@ -0,0 +1,15 @@
+\title{\code{fly sync}}{fly-sync}
+\use-plugin{concourse-docs}
+
+Occasionally we add additional features to \code{fly} or make changes to the
+communication between it and Concourse's API server. To make sure you're
+running the latest and greatest version that works with the Concourse you
+are targeting we provide a command called \code{sync} that will update your
+local \code{fly}. It can be used like so:
+
+\codeblock{bash}{{
+$ fly -t example sync
+}}
+
+The \code{fly} command will also warn you if it notices that your CLI version
+is out of sync with the server.
\ No newline at end of file
diff --git a/lit/references/fly/targets.lit b/lit/references/fly/targets.lit
new file mode 100644
index 00000000..8b65dea0
--- /dev/null
+++ b/lit/references/fly/targets.lit
@@ -0,0 +1,10 @@
+\title{\code{fly targets}}{fly-targets}
+\use-plugin{concourse-docs}
+
+To see what targets are currently known to \code{fly}, run:
+
+\codeblock{bash}{{
+$ fly targets
+}}
+
+This will show each target's name, URL, and when its token expires.
diff --git a/lit/references/fly/unpause-pipeline.lit b/lit/references/fly/unpause-pipeline.lit
new file mode 100644
index 00000000..4e02d755
--- /dev/null
+++ b/lit/references/fly/unpause-pipeline.lit
@@ -0,0 +1,10 @@
+\title{\code{fly unpause-pipeline}}{fly-unpause-pipeline}
+\use-plugin{concourse-docs}
+
+To unpause a pipeline, run:
+
+\codeblock{bash}{{
+$ fly -t example unpause-pipeline --pipeline my-pipeline
+}}
+
+This will resume job scheduling and resource checking.
\ No newline at end of file
diff --git a/lit/references/fly/userinfo.lit b/lit/references/fly/userinfo.lit
new file mode 100644
index 00000000..7907fe7a
--- /dev/null
+++ b/lit/references/fly/userinfo.lit
@@ -0,0 +1,9 @@
+\title{\code{fly userinfo}}{fly-userinfo}
+\use-plugin{concourse-docs}
+
+To check what user you're logged in as, as well as which teams you are
+currently authenticated to and which roles within each team you have, run:
+
+\codeblock{bash}{{
+$ fly -t example userinfo
+}}
\ No newline at end of file
diff --git a/lit/references/fly/validate-pipeline.lit b/lit/references/fly/validate-pipeline.lit
new file mode 100644
index 00000000..a6f87b13
--- /dev/null
+++ b/lit/references/fly/validate-pipeline.lit
@@ -0,0 +1,12 @@
+\title{\code{fly validate-pipeline}}{fly-validate-pipeline}
+\use-plugin{concourse-docs}
+
+To validate a local pipeline configuration without submitting it to Concourse,
+run \code{validate-pipeline}:
+
+\codeblock{bash}{{
+$ fly validate-pipeline --config pipeline.yml
+}}
+
+By default, pipeline errors will cause \code{validate-pipeline} to fail, but
+warnings won't. To fail on both errors and warnings, pass the `--strict` flag.
\ No newline at end of file
diff --git a/lit/docs/pipelines.lit b/lit/references/pipelines.lit
similarity index 97%
rename from lit/docs/pipelines.lit
rename to lit/references/pipelines.lit
index d7cc57cc..b8a3e15a 100644
--- a/lit/docs/pipelines.lit
+++ b/lit/references/pipelines.lit
@@ -134,11 +134,6 @@ files} which conform to the following schema:
   }
 }
 
-\table-of-contents
-
-\include-section{pipelines/configuring.lit}
-\include-section{pipelines/managing.lit}
-\include-section{pipelines/instance-groups.lit}
 
 \right-side{Examples}{
   \example{Hello, world!}{
diff --git a/lit/docs/resource-types.lit b/lit/references/resource-types.lit
similarity index 99%
rename from lit/docs/resource-types.lit
rename to lit/references/resource-types.lit
index 61f6fec4..6953154b 100644
--- a/lit/docs/resource-types.lit
+++ b/lit/references/resource-types.lit
@@ -176,7 +176,6 @@ A pipeline's resource types are listed under
 }
 
 \split-sections
-\table-of-contents
 
 \include-section{./resource-types/implementing.lit}
 \include-section{./resource-types/managing.lit}
diff --git a/lit/docs/resource-types/implementing.lit b/lit/references/resource-types/implementing.lit
similarity index 100%
rename from lit/docs/resource-types/implementing.lit
rename to lit/references/resource-types/implementing.lit
diff --git a/lit/docs/resource-types/managing.lit b/lit/references/resource-types/managing.lit
similarity index 100%
rename from lit/docs/resource-types/managing.lit
rename to lit/references/resource-types/managing.lit
diff --git a/lit/users.lit b/lit/users.lit
new file mode 100644
index 00000000..3945f85d
--- /dev/null
+++ b/lit/users.lit
@@ -0,0 +1,6 @@
+\title{Users}{users}
+\use-plugin{concourse-docs}
+
+Anything for advanced users
+
+\include-section{users/managing-pipelines.lit}
diff --git a/lit/users/managing-pipelines.lit b/lit/users/managing-pipelines.lit
new file mode 100644
index 00000000..f4447325
--- /dev/null
+++ b/lit/users/managing-pipelines.lit
@@ -0,0 +1,4 @@
+\title{Managing Pipelines}{managing-pipelines}
+
+\use-plugin{concourse-docs}
+

From b09bf314572817a8e845efeba184cfd7ba808307 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 14:42:25 +0100
Subject: [PATCH 04/26] Create a fly CLI subcommand template

See references/fly/_template.lit

It contains a structure how a possible fly CLI
command could look like.
A comment inside the file describe how to use it.

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/references/fly.lit           |  4 +-
 lit/references/fly/_template.lit | 89 ++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 lit/references/fly/_template.lit

diff --git a/lit/references/fly.lit b/lit/references/fly.lit
index 5ec0e678..b3889b74 100644
--- a/lit/references/fly.lit
+++ b/lit/references/fly.lit
@@ -12,7 +12,7 @@ every command and flag. Once you've learned what the commands do, you may want
 to consult \code{fly -h} to learn the short forms.
 
 \section{
-  \title{Global options}
+  \title{Global options}{fly-global-options}
 
   {-
   tomschr: maybe this could be a bit more verbose. For example,
@@ -33,6 +33,8 @@ to consult \code{fly -h} to learn the short forms.
 
 \table-of-contents
 
+\include-section{fly/_template.lit}
+
 \include-section{fly/archive-pipeline.lit}
 \include-section{fly/completion.lit}
 \include-section{fly/delete-target.lit}
diff --git a/lit/references/fly/_template.lit b/lit/references/fly/_template.lit
new file mode 100644
index 00000000..c5d6c61f
--- /dev/null
+++ b/lit/references/fly/_template.lit
@@ -0,0 +1,89 @@
+{-
+This is a reference template for a fly command
+
+To add a new command, copy this template and
+name the new file according to the command.
+
+Here is a short checklist that needs to be changed:
+
+* Change the 2nd argument in \title, the ID
+  so it adheres to the syntax foo-<COMMAND>
+* Add the purpose of the command
+* Correct the synopsis
+* Add a short description
+* List all options and a short explanation.
+* Describe possible errors
+* Give some helpful examples.
+  If it makes sense, add command and its output.
+* Add references to related commands in the
+  "See also" section
+
+-}
+
+\title{Template: \code{fly foo}}{fly-foo}
+\use-plugin{concourse-docs}
+\single-page
+\omit-children-from-table-of-contents
+
+\section{
+    \title{Purpose}
+    Makes foo things
+    {-
+    TODO:
+    If useful, add the version when the
+    command first appeard in Concourse
+    -}
+}
+
+
+\section{
+    \title{Synopsis}
+    \codeblock{text}{{
+    fly [OPTIONS] foo [foo-OPTIONS]
+    }}
+}
+
+\section{
+    \title{Description}
+    The foo subcommand does...
+}
+
+\section{
+    \title{Options}
+    See also \reference{fly-global-options}
+
+    \definitions{
+        \definition{\code{-t}, \code{--target=}}{
+            Concourse target name
+        }
+    }{
+        \definition{\code{--force}}{Force the action}
+    }{
+        \definition{\code{-x}, \code{--expert}}{
+            Enable the expert mode
+        }
+    }
+}
+
+
+\section{
+    \title{Exit status}
+    Do we need this section?
+}
+
+
+\section{
+    \title{Errors}
+}
+
+\section{
+    \title{Examples}
+    \codeblock{bash}{{
+    $ fly foo -x
+    Expert mode enabled
+    }}
+}
+
+\section{
+    \title{See also}
+}
\ No newline at end of file

From 974b23ae1cdb2826472849221c63540d04428557 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 14:48:05 +0100
Subject: [PATCH 05/26] Move internals from docs to reference

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                             | 1 -
 lit/references.lit                                       | 3 ++-
 lit/{docs => references}/internals.lit                   | 0
 lit/{docs => references}/internals/build-tracker.lit     | 0
 lit/{docs => references}/internals/checker.lit           | 0
 lit/{docs => references}/internals/garbage-collector.lit | 0
 lit/{docs => references}/internals/scheduler.lit         | 0
 7 files changed, 2 insertions(+), 2 deletions(-)
 rename lit/{docs => references}/internals.lit (100%)
 rename lit/{docs => references}/internals/build-tracker.lit (100%)
 rename lit/{docs => references}/internals/checker.lit (100%)
 rename lit/{docs => references}/internals/garbage-collector.lit (100%)
 rename lit/{docs => references}/internals/scheduler.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 9aca0430..d78acac0 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -59,7 +59,6 @@ the "big picture" as the mental model sets in.
 \include-section{./docs/how-to-guides.lit}
 \include-section{./docs/operation.lit}
 \include-section{./docs/observation.lit}
-\include-section{./docs/internals.lit}
 
 \split-sections
 \table-of-contents
diff --git a/lit/references.lit b/lit/references.lit
index 27bc52d6..b4044710 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -16,4 +16,5 @@ Contains a reference of:
 
 \include-section{./references/fly.lit}
 \include-section{./references/resource-types.lit}
-\include-section{./references/pipelines.lit}
\ No newline at end of file
+\include-section{./references/pipelines.lit}
+\include-section{./references/internals.lit}
diff --git a/lit/docs/internals.lit b/lit/references/internals.lit
similarity index 100%
rename from lit/docs/internals.lit
rename to lit/references/internals.lit
diff --git a/lit/docs/internals/build-tracker.lit b/lit/references/internals/build-tracker.lit
similarity index 100%
rename from lit/docs/internals/build-tracker.lit
rename to lit/references/internals/build-tracker.lit
diff --git a/lit/docs/internals/checker.lit b/lit/references/internals/checker.lit
similarity index 100%
rename from lit/docs/internals/checker.lit
rename to lit/references/internals/checker.lit
diff --git a/lit/docs/internals/garbage-collector.lit b/lit/references/internals/garbage-collector.lit
similarity index 100%
rename from lit/docs/internals/garbage-collector.lit
rename to lit/references/internals/garbage-collector.lit
diff --git a/lit/docs/internals/scheduler.lit b/lit/references/internals/scheduler.lit
similarity index 100%
rename from lit/docs/internals/scheduler.lit
rename to lit/references/internals/scheduler.lit

From f53f697e79f12ed5121d5f49f24cb9108cbd72b7 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 14:56:22 +0100
Subject: [PATCH 06/26] Move install from docs to users

Create a new "Introduction" section; move
content from the first paragraphs of doc
to this new section

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                  | 45 -----------------
 lit/users.lit                                 | 50 +++++++++++++++++++
 lit/{docs => users}/install.lit               |  2 +-
 lit/{docs => users}/install/concourse-cli.lit |  0
 lit/{docs => users}/install/db.lit            |  0
 .../install/generating-keys.lit               |  0
 lit/{docs => users}/install/upgrading.lit     |  0
 lit/{docs => users}/install/web.lit           |  0
 lit/{docs => users}/install/worker.lit        |  0
 9 files changed, 51 insertions(+), 46 deletions(-)
 rename lit/{docs => users}/install.lit (97%)
 rename lit/{docs => users}/install/concourse-cli.lit (100%)
 rename lit/{docs => users}/install/db.lit (100%)
 rename lit/{docs => users}/install/generating-keys.lit (100%)
 rename lit/{docs => users}/install/upgrading.lit (100%)
 rename lit/{docs => users}/install/web.lit (100%)
 rename lit/{docs => users}/install/worker.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index d78acac0..9c2dfe45 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -2,52 +2,7 @@
 
 \use-plugin{concourse-docs}
 
-Concourse is a pipeline-based continuous thing-doer.
 
-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.
-
-\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.
-
-\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
-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{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.
-
-Everything in Concourse runs in a container. Instead of modifying workers to
-install build tools, \reference{tasks} describe 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.
-
-
-\include-section{./docs/install.lit}
 \include-section{./docs/auth.lit}
 \include-section{./docs/config.lit}
 \include-section{./docs/vars.lit}
diff --git a/lit/users.lit b/lit/users.lit
index 3945f85d..1b7403ec 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -1,6 +1,56 @@
 \title{Users}{users}
 \use-plugin{concourse-docs}
+\split-sections
 
 Anything for advanced users
 
+\section{
+    \title{Introduction}
+    Concourse is a pipeline-based continuous thing-doer.
+
+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.
+
+\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.
+
+\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
+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{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.
+
+Everything in Concourse runs in a container. Instead of modifying workers to
+install build tools, \reference{tasks} describe 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.
+
+}
+
+\include-section{users/install.lit}
 \include-section{users/managing-pipelines.lit}
diff --git a/lit/docs/install.lit b/lit/users/install.lit
similarity index 97%
rename from lit/docs/install.lit
rename to lit/users/install.lit
index 8a614ce5..44b36cae 100644
--- a/lit/docs/install.lit
+++ b/lit/users/install.lit
@@ -1,4 +1,4 @@
-\title{Install}{install}
+\title{Installing Concourse}{install}
 
 \use-plugin{concourse-docs}
 
diff --git a/lit/docs/install/concourse-cli.lit b/lit/users/install/concourse-cli.lit
similarity index 100%
rename from lit/docs/install/concourse-cli.lit
rename to lit/users/install/concourse-cli.lit
diff --git a/lit/docs/install/db.lit b/lit/users/install/db.lit
similarity index 100%
rename from lit/docs/install/db.lit
rename to lit/users/install/db.lit
diff --git a/lit/docs/install/generating-keys.lit b/lit/users/install/generating-keys.lit
similarity index 100%
rename from lit/docs/install/generating-keys.lit
rename to lit/users/install/generating-keys.lit
diff --git a/lit/docs/install/upgrading.lit b/lit/users/install/upgrading.lit
similarity index 100%
rename from lit/docs/install/upgrading.lit
rename to lit/users/install/upgrading.lit
diff --git a/lit/docs/install/web.lit b/lit/users/install/web.lit
similarity index 100%
rename from lit/docs/install/web.lit
rename to lit/users/install/web.lit
diff --git a/lit/docs/install/worker.lit b/lit/users/install/worker.lit
similarity index 100%
rename from lit/docs/install/worker.lit
rename to lit/users/install/worker.lit

From 215e0344abd212d90c0f11c35b299c2dc2af2d6d Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:00:06 +0100
Subject: [PATCH 07/26] Move auth from docs to references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                                | 1 -
 lit/references.lit                                          | 2 ++
 lit/{docs => references}/auth.lit                           | 0
 lit/{docs => references}/auth/configuring.lit               | 0
 lit/{docs => references}/auth/configuring/bitbucket.lit     | 0
 lit/{docs => references}/auth/configuring/cf.lit            | 0
 lit/{docs => references}/auth/configuring/generic-oauth.lit | 0
 lit/{docs => references}/auth/configuring/generic-oidc.lit  | 0
 lit/{docs => references}/auth/configuring/generic-saml.lit  | 0
 lit/{docs => references}/auth/configuring/github.lit        | 0
 lit/{docs => references}/auth/configuring/gitlab.lit        | 0
 lit/{docs => references}/auth/configuring/ldap.lit          | 0
 lit/{docs => references}/auth/configuring/local.lit         | 0
 lit/{docs => references}/auth/configuring/microsoft.lit     | 0
 lit/{docs => references}/auth/main-team.lit                 | 0
 lit/{docs => references}/auth/managing-teams.lit            | 0
 lit/{docs => references}/auth/roles.lit                     | 0
 17 files changed, 2 insertions(+), 1 deletion(-)
 rename lit/{docs => references}/auth.lit (100%)
 rename lit/{docs => references}/auth/configuring.lit (100%)
 rename lit/{docs => references}/auth/configuring/bitbucket.lit (100%)
 rename lit/{docs => references}/auth/configuring/cf.lit (100%)
 rename lit/{docs => references}/auth/configuring/generic-oauth.lit (100%)
 rename lit/{docs => references}/auth/configuring/generic-oidc.lit (100%)
 rename lit/{docs => references}/auth/configuring/generic-saml.lit (100%)
 rename lit/{docs => references}/auth/configuring/github.lit (100%)
 rename lit/{docs => references}/auth/configuring/gitlab.lit (100%)
 rename lit/{docs => references}/auth/configuring/ldap.lit (100%)
 rename lit/{docs => references}/auth/configuring/local.lit (100%)
 rename lit/{docs => references}/auth/configuring/microsoft.lit (100%)
 rename lit/{docs => references}/auth/main-team.lit (100%)
 rename lit/{docs => references}/auth/managing-teams.lit (100%)
 rename lit/{docs => references}/auth/roles.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 9c2dfe45..cead6bde 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -3,7 +3,6 @@
 \use-plugin{concourse-docs}
 
 
-\include-section{./docs/auth.lit}
 \include-section{./docs/config.lit}
 \include-section{./docs/vars.lit}
 \include-section{./docs/resources.lit}
diff --git a/lit/references.lit b/lit/references.lit
index b4044710..8ac528a2 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -17,4 +17,6 @@ Contains a reference of:
 \include-section{./references/fly.lit}
 \include-section{./references/resource-types.lit}
 \include-section{./references/pipelines.lit}
+\include-section{./references/auth.lit}
+
 \include-section{./references/internals.lit}
diff --git a/lit/docs/auth.lit b/lit/references/auth.lit
similarity index 100%
rename from lit/docs/auth.lit
rename to lit/references/auth.lit
diff --git a/lit/docs/auth/configuring.lit b/lit/references/auth/configuring.lit
similarity index 100%
rename from lit/docs/auth/configuring.lit
rename to lit/references/auth/configuring.lit
diff --git a/lit/docs/auth/configuring/bitbucket.lit b/lit/references/auth/configuring/bitbucket.lit
similarity index 100%
rename from lit/docs/auth/configuring/bitbucket.lit
rename to lit/references/auth/configuring/bitbucket.lit
diff --git a/lit/docs/auth/configuring/cf.lit b/lit/references/auth/configuring/cf.lit
similarity index 100%
rename from lit/docs/auth/configuring/cf.lit
rename to lit/references/auth/configuring/cf.lit
diff --git a/lit/docs/auth/configuring/generic-oauth.lit b/lit/references/auth/configuring/generic-oauth.lit
similarity index 100%
rename from lit/docs/auth/configuring/generic-oauth.lit
rename to lit/references/auth/configuring/generic-oauth.lit
diff --git a/lit/docs/auth/configuring/generic-oidc.lit b/lit/references/auth/configuring/generic-oidc.lit
similarity index 100%
rename from lit/docs/auth/configuring/generic-oidc.lit
rename to lit/references/auth/configuring/generic-oidc.lit
diff --git a/lit/docs/auth/configuring/generic-saml.lit b/lit/references/auth/configuring/generic-saml.lit
similarity index 100%
rename from lit/docs/auth/configuring/generic-saml.lit
rename to lit/references/auth/configuring/generic-saml.lit
diff --git a/lit/docs/auth/configuring/github.lit b/lit/references/auth/configuring/github.lit
similarity index 100%
rename from lit/docs/auth/configuring/github.lit
rename to lit/references/auth/configuring/github.lit
diff --git a/lit/docs/auth/configuring/gitlab.lit b/lit/references/auth/configuring/gitlab.lit
similarity index 100%
rename from lit/docs/auth/configuring/gitlab.lit
rename to lit/references/auth/configuring/gitlab.lit
diff --git a/lit/docs/auth/configuring/ldap.lit b/lit/references/auth/configuring/ldap.lit
similarity index 100%
rename from lit/docs/auth/configuring/ldap.lit
rename to lit/references/auth/configuring/ldap.lit
diff --git a/lit/docs/auth/configuring/local.lit b/lit/references/auth/configuring/local.lit
similarity index 100%
rename from lit/docs/auth/configuring/local.lit
rename to lit/references/auth/configuring/local.lit
diff --git a/lit/docs/auth/configuring/microsoft.lit b/lit/references/auth/configuring/microsoft.lit
similarity index 100%
rename from lit/docs/auth/configuring/microsoft.lit
rename to lit/references/auth/configuring/microsoft.lit
diff --git a/lit/docs/auth/main-team.lit b/lit/references/auth/main-team.lit
similarity index 100%
rename from lit/docs/auth/main-team.lit
rename to lit/references/auth/main-team.lit
diff --git a/lit/docs/auth/managing-teams.lit b/lit/references/auth/managing-teams.lit
similarity index 100%
rename from lit/docs/auth/managing-teams.lit
rename to lit/references/auth/managing-teams.lit
diff --git a/lit/docs/auth/roles.lit b/lit/references/auth/roles.lit
similarity index 100%
rename from lit/docs/auth/roles.lit
rename to lit/references/auth/roles.lit

From aa798d97d7894f6fc5cf28fd61ab2e85bba8809b Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:02:02 +0100
Subject: [PATCH 08/26] Move resources from docs to references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                    | 1 -
 lit/references.lit                              | 1 +
 lit/{docs => references}/resources.lit          | 0
 lit/{docs => references}/resources/managing.lit | 0
 lit/{docs => references}/resources/versions.lit | 0
 5 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/resources.lit (100%)
 rename lit/{docs => references}/resources/managing.lit (100%)
 rename lit/{docs => references}/resources/versions.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index cead6bde..76154216 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -5,7 +5,6 @@
 
 \include-section{./docs/config.lit}
 \include-section{./docs/vars.lit}
-\include-section{./docs/resources.lit}
 \include-section{./docs/jobs.lit}
 \include-section{./docs/steps.lit}
 \include-section{./docs/tasks.lit}
diff --git a/lit/references.lit b/lit/references.lit
index 8ac528a2..38388715 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -15,6 +15,7 @@ Contains a reference of:
 -}
 
 \include-section{./references/fly.lit}
+\include-section{./references/resources.lit}
 \include-section{./references/resource-types.lit}
 \include-section{./references/pipelines.lit}
 \include-section{./references/auth.lit}
diff --git a/lit/docs/resources.lit b/lit/references/resources.lit
similarity index 100%
rename from lit/docs/resources.lit
rename to lit/references/resources.lit
diff --git a/lit/docs/resources/managing.lit b/lit/references/resources/managing.lit
similarity index 100%
rename from lit/docs/resources/managing.lit
rename to lit/references/resources/managing.lit
diff --git a/lit/docs/resources/versions.lit b/lit/references/resources/versions.lit
similarity index 100%
rename from lit/docs/resources/versions.lit
rename to lit/references/resources/versions.lit

From 356583ade11017ef3b9d7e7f4c6b2758922909a4 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:08:23 +0100
Subject: [PATCH 09/26] Move tasks from docs into references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                   | 1 -
 lit/references.lit                             | 1 +
 lit/{docs => references}/tasks.lit             | 0
 lit/{docs => references}/tasks/environment.lit | 0
 lit/{docs => references}/tasks/running.lit     | 0
 5 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/tasks.lit (100%)
 rename lit/{docs => references}/tasks/environment.lit (100%)
 rename lit/{docs => references}/tasks/running.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 76154216..12e4c383 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -7,7 +7,6 @@
 \include-section{./docs/vars.lit}
 \include-section{./docs/jobs.lit}
 \include-section{./docs/steps.lit}
-\include-section{./docs/tasks.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
 \include-section{./docs/operation.lit}
diff --git a/lit/references.lit b/lit/references.lit
index 38388715..4210cdc4 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -18,6 +18,7 @@ Contains a reference of:
 \include-section{./references/resources.lit}
 \include-section{./references/resource-types.lit}
 \include-section{./references/pipelines.lit}
+\include-section{./references/tasks.lit}
 \include-section{./references/auth.lit}
 
 \include-section{./references/internals.lit}
diff --git a/lit/docs/tasks.lit b/lit/references/tasks.lit
similarity index 100%
rename from lit/docs/tasks.lit
rename to lit/references/tasks.lit
diff --git a/lit/docs/tasks/environment.lit b/lit/references/tasks/environment.lit
similarity index 100%
rename from lit/docs/tasks/environment.lit
rename to lit/references/tasks/environment.lit
diff --git a/lit/docs/tasks/running.lit b/lit/references/tasks/running.lit
similarity index 100%
rename from lit/docs/tasks/running.lit
rename to lit/references/tasks/running.lit

From 3798890ff781f82cb566ea186c51365a677000b1 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:09:26 +0100
Subject: [PATCH 10/26] Move steps from docs into references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                       | 1 -
 lit/references.lit                 | 1 +
 lit/{docs => references}/steps.lit | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/steps.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 12e4c383..f311df76 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -6,7 +6,6 @@
 \include-section{./docs/config.lit}
 \include-section{./docs/vars.lit}
 \include-section{./docs/jobs.lit}
-\include-section{./docs/steps.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
 \include-section{./docs/operation.lit}
diff --git a/lit/references.lit b/lit/references.lit
index 4210cdc4..dfc5c1c8 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -19,6 +19,7 @@ Contains a reference of:
 \include-section{./references/resource-types.lit}
 \include-section{./references/pipelines.lit}
 \include-section{./references/tasks.lit}
+\include-section{./references/steps.lit}
 \include-section{./references/auth.lit}
 
 \include-section{./references/internals.lit}
diff --git a/lit/docs/steps.lit b/lit/references/steps.lit
similarity index 100%
rename from lit/docs/steps.lit
rename to lit/references/steps.lit

From 22dd5edc073d7726c6742394714b95bc33130fd4 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:11:19 +0100
Subject: [PATCH 11/26] Move jobs from docs into references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                               | 1 -
 lit/references.lit                         | 1 +
 lit/{docs => references}/jobs.lit          | 0
 lit/{docs => references}/jobs/managing.lit | 0
 4 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/jobs.lit (100%)
 rename lit/{docs => references}/jobs/managing.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index f311df76..b47af018 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -5,7 +5,6 @@
 
 \include-section{./docs/config.lit}
 \include-section{./docs/vars.lit}
-\include-section{./docs/jobs.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
 \include-section{./docs/operation.lit}
diff --git a/lit/references.lit b/lit/references.lit
index dfc5c1c8..ff9f72e5 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -18,6 +18,7 @@ Contains a reference of:
 \include-section{./references/resources.lit}
 \include-section{./references/resource-types.lit}
 \include-section{./references/pipelines.lit}
+\include-section{./references/jobs.lit}
 \include-section{./references/tasks.lit}
 \include-section{./references/steps.lit}
 \include-section{./references/auth.lit}
diff --git a/lit/docs/jobs.lit b/lit/references/jobs.lit
similarity index 100%
rename from lit/docs/jobs.lit
rename to lit/references/jobs.lit
diff --git a/lit/docs/jobs/managing.lit b/lit/references/jobs/managing.lit
similarity index 100%
rename from lit/docs/jobs/managing.lit
rename to lit/references/jobs/managing.lit

From b9b30badb7cbf0af89ab16ee905d84d9f1dc2e7b Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:13:46 +0100
Subject: [PATCH 12/26] Move vars from docs into references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                      | 1 -
 lit/references.lit                | 1 +
 lit/{docs => references}/vars.lit | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/vars.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index b47af018..9586c184 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -4,7 +4,6 @@
 
 
 \include-section{./docs/config.lit}
-\include-section{./docs/vars.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
 \include-section{./docs/operation.lit}
diff --git a/lit/references.lit b/lit/references.lit
index ff9f72e5..028c11a3 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -17,6 +17,7 @@ Contains a reference of:
 \include-section{./references/fly.lit}
 \include-section{./references/resources.lit}
 \include-section{./references/resource-types.lit}
+\include-section{./references/vars.lit}
 \include-section{./references/pipelines.lit}
 \include-section{./references/jobs.lit}
 \include-section{./references/tasks.lit}
diff --git a/lit/docs/vars.lit b/lit/references/vars.lit
similarity index 100%
rename from lit/docs/vars.lit
rename to lit/references/vars.lit

From c9b140c2a0847d9ff01bf14c27cc0032a119c89d Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:15:26 +0100
Subject: [PATCH 13/26] Move operation from docs into references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                                    | 1 -
 lit/references.lit                                              | 1 +
 lit/{docs => references}/operation.lit                          | 0
 lit/{docs => references}/operation/administration.lit           | 0
 lit/{docs => references}/operation/container-placement.lit      | 0
 lit/{docs => references}/operation/creds.lit                    | 0
 lit/{docs => references}/operation/creds/aws-secretsmanager.lit | 0
 lit/{docs => references}/operation/creds/aws-ssm.lit            | 0
 lit/{docs => references}/operation/creds/caching.lit            | 0
 lit/{docs => references}/operation/creds/credhub.lit            | 0
 lit/{docs => references}/operation/creds/cyberark-conjur.lit    | 0
 lit/{docs => references}/operation/creds/kubernetes.lit         | 0
 lit/{docs => references}/operation/creds/redacting.lit          | 0
 lit/{docs => references}/operation/creds/retry.lit              | 0
 lit/{docs => references}/operation/creds/vault.lit              | 0
 lit/{docs => references}/operation/encryption.lit               | 0
 lit/{docs => references}/operation/global-resources.lit         | 0
 lit/{docs => references}/operation/metrics.lit                  | 0
 lit/{docs => references}/operation/opa.lit                      | 0
 lit/{docs => references}/operation/tracing.lit                  | 0
 20 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/operation.lit (100%)
 rename lit/{docs => references}/operation/administration.lit (100%)
 rename lit/{docs => references}/operation/container-placement.lit (100%)
 rename lit/{docs => references}/operation/creds.lit (100%)
 rename lit/{docs => references}/operation/creds/aws-secretsmanager.lit (100%)
 rename lit/{docs => references}/operation/creds/aws-ssm.lit (100%)
 rename lit/{docs => references}/operation/creds/caching.lit (100%)
 rename lit/{docs => references}/operation/creds/credhub.lit (100%)
 rename lit/{docs => references}/operation/creds/cyberark-conjur.lit (100%)
 rename lit/{docs => references}/operation/creds/kubernetes.lit (100%)
 rename lit/{docs => references}/operation/creds/redacting.lit (100%)
 rename lit/{docs => references}/operation/creds/retry.lit (100%)
 rename lit/{docs => references}/operation/creds/vault.lit (100%)
 rename lit/{docs => references}/operation/encryption.lit (100%)
 rename lit/{docs => references}/operation/global-resources.lit (100%)
 rename lit/{docs => references}/operation/metrics.lit (100%)
 rename lit/{docs => references}/operation/opa.lit (100%)
 rename lit/{docs => references}/operation/tracing.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 9586c184..1ec0238c 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -6,7 +6,6 @@
 \include-section{./docs/config.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
-\include-section{./docs/operation.lit}
 \include-section{./docs/observation.lit}
 
 \split-sections
diff --git a/lit/references.lit b/lit/references.lit
index 028c11a3..34b2851a 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -23,5 +23,6 @@ Contains a reference of:
 \include-section{./references/tasks.lit}
 \include-section{./references/steps.lit}
 \include-section{./references/auth.lit}
+\include-section{./references/operation.lit}
 
 \include-section{./references/internals.lit}
diff --git a/lit/docs/operation.lit b/lit/references/operation.lit
similarity index 100%
rename from lit/docs/operation.lit
rename to lit/references/operation.lit
diff --git a/lit/docs/operation/administration.lit b/lit/references/operation/administration.lit
similarity index 100%
rename from lit/docs/operation/administration.lit
rename to lit/references/operation/administration.lit
diff --git a/lit/docs/operation/container-placement.lit b/lit/references/operation/container-placement.lit
similarity index 100%
rename from lit/docs/operation/container-placement.lit
rename to lit/references/operation/container-placement.lit
diff --git a/lit/docs/operation/creds.lit b/lit/references/operation/creds.lit
similarity index 100%
rename from lit/docs/operation/creds.lit
rename to lit/references/operation/creds.lit
diff --git a/lit/docs/operation/creds/aws-secretsmanager.lit b/lit/references/operation/creds/aws-secretsmanager.lit
similarity index 100%
rename from lit/docs/operation/creds/aws-secretsmanager.lit
rename to lit/references/operation/creds/aws-secretsmanager.lit
diff --git a/lit/docs/operation/creds/aws-ssm.lit b/lit/references/operation/creds/aws-ssm.lit
similarity index 100%
rename from lit/docs/operation/creds/aws-ssm.lit
rename to lit/references/operation/creds/aws-ssm.lit
diff --git a/lit/docs/operation/creds/caching.lit b/lit/references/operation/creds/caching.lit
similarity index 100%
rename from lit/docs/operation/creds/caching.lit
rename to lit/references/operation/creds/caching.lit
diff --git a/lit/docs/operation/creds/credhub.lit b/lit/references/operation/creds/credhub.lit
similarity index 100%
rename from lit/docs/operation/creds/credhub.lit
rename to lit/references/operation/creds/credhub.lit
diff --git a/lit/docs/operation/creds/cyberark-conjur.lit b/lit/references/operation/creds/cyberark-conjur.lit
similarity index 100%
rename from lit/docs/operation/creds/cyberark-conjur.lit
rename to lit/references/operation/creds/cyberark-conjur.lit
diff --git a/lit/docs/operation/creds/kubernetes.lit b/lit/references/operation/creds/kubernetes.lit
similarity index 100%
rename from lit/docs/operation/creds/kubernetes.lit
rename to lit/references/operation/creds/kubernetes.lit
diff --git a/lit/docs/operation/creds/redacting.lit b/lit/references/operation/creds/redacting.lit
similarity index 100%
rename from lit/docs/operation/creds/redacting.lit
rename to lit/references/operation/creds/redacting.lit
diff --git a/lit/docs/operation/creds/retry.lit b/lit/references/operation/creds/retry.lit
similarity index 100%
rename from lit/docs/operation/creds/retry.lit
rename to lit/references/operation/creds/retry.lit
diff --git a/lit/docs/operation/creds/vault.lit b/lit/references/operation/creds/vault.lit
similarity index 100%
rename from lit/docs/operation/creds/vault.lit
rename to lit/references/operation/creds/vault.lit
diff --git a/lit/docs/operation/encryption.lit b/lit/references/operation/encryption.lit
similarity index 100%
rename from lit/docs/operation/encryption.lit
rename to lit/references/operation/encryption.lit
diff --git a/lit/docs/operation/global-resources.lit b/lit/references/operation/global-resources.lit
similarity index 100%
rename from lit/docs/operation/global-resources.lit
rename to lit/references/operation/global-resources.lit
diff --git a/lit/docs/operation/metrics.lit b/lit/references/operation/metrics.lit
similarity index 100%
rename from lit/docs/operation/metrics.lit
rename to lit/references/operation/metrics.lit
diff --git a/lit/docs/operation/opa.lit b/lit/references/operation/opa.lit
similarity index 100%
rename from lit/docs/operation/opa.lit
rename to lit/references/operation/opa.lit
diff --git a/lit/docs/operation/tracing.lit b/lit/references/operation/tracing.lit
similarity index 100%
rename from lit/docs/operation/tracing.lit
rename to lit/references/operation/tracing.lit

From a15dcdaaf754037731f13d7e960d4cd79cd2d8a5 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:17:44 +0100
Subject: [PATCH 14/26] Move observation from docs into references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                             | 1 -
 lit/references.lit                       | 1 +
 lit/{docs => references}/observation.lit | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => references}/observation.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 1ec0238c..f3e5f431 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -6,7 +6,6 @@
 \include-section{./docs/config.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
-\include-section{./docs/observation.lit}
 
 \split-sections
 \table-of-contents
diff --git a/lit/references.lit b/lit/references.lit
index 34b2851a..637fd670 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -24,5 +24,6 @@ Contains a reference of:
 \include-section{./references/steps.lit}
 \include-section{./references/auth.lit}
 \include-section{./references/operation.lit}
+\include-section{./references/observation.lit}
 
 \include-section{./references/internals.lit}
diff --git a/lit/docs/observation.lit b/lit/references/observation.lit
similarity index 100%
rename from lit/docs/observation.lit
rename to lit/references/observation.lit

From a9d305ea95b45c1016fc846d5c09dd613ac05017 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:20:03 +0100
Subject: [PATCH 15/26] Move config from docs into users

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                                 | 1 -
 lit/users.lit                                | 1 +
 lit/{docs => users}/config.lit               | 0
 lit/{docs => users}/config/basic-schemas.lit | 0
 lit/{docs => users}/config/vars/caching.lit  | 0
 lit/{docs => users}/config/yaml.lit          | 0
 6 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => users}/config.lit (100%)
 rename lit/{docs => users}/config/basic-schemas.lit (100%)
 rename lit/{docs => users}/config/vars/caching.lit (100%)
 rename lit/{docs => users}/config/yaml.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index f3e5f431..8e924a75 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -3,7 +3,6 @@
 \use-plugin{concourse-docs}
 
 
-\include-section{./docs/config.lit}
 \include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
 
diff --git a/lit/users.lit b/lit/users.lit
index 1b7403ec..06365f7a 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -53,4 +53,5 @@ the "big picture" as the mental model sets in.
 }
 
 \include-section{users/install.lit}
+\include-section{users/config.lit}
 \include-section{users/managing-pipelines.lit}
diff --git a/lit/docs/config.lit b/lit/users/config.lit
similarity index 100%
rename from lit/docs/config.lit
rename to lit/users/config.lit
diff --git a/lit/docs/config/basic-schemas.lit b/lit/users/config/basic-schemas.lit
similarity index 100%
rename from lit/docs/config/basic-schemas.lit
rename to lit/users/config/basic-schemas.lit
diff --git a/lit/docs/config/vars/caching.lit b/lit/users/config/vars/caching.lit
similarity index 100%
rename from lit/docs/config/vars/caching.lit
rename to lit/users/config/vars/caching.lit
diff --git a/lit/docs/config/yaml.lit b/lit/users/config/yaml.lit
similarity index 100%
rename from lit/docs/config/yaml.lit
rename to lit/users/config/yaml.lit

From d755c0e53701a5e8af5a981ca4aee7bd908b28bb Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:29:05 +0100
Subject: [PATCH 16/26] Move some fly subcommands to references

* Move abort-build, builds, intercept, and watch
  subcommand to fly cli reference
* Adapt file references

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs/builds.lit                | 140 -----------------------------
 lit/references/fly.lit             |   4 +
 lit/references/fly/abort-build.lit |  11 +++
 lit/references/fly/builds.lit      |  24 +++++
 lit/references/fly/intercept.lit   |  65 ++++++++++++++
 lit/references/fly/watch.lit       |  33 +++++++
 6 files changed, 137 insertions(+), 140 deletions(-)
 create mode 100644 lit/references/fly/abort-build.lit
 create mode 100644 lit/references/fly/builds.lit
 create mode 100644 lit/references/fly/intercept.lit
 create mode 100644 lit/references/fly/watch.lit

diff --git a/lit/docs/builds.lit b/lit/docs/builds.lit
index 729ad866..210195a5 100644
--- a/lit/docs/builds.lit
+++ b/lit/docs/builds.lit
@@ -68,143 +68,3 @@ sure you intercept while it's running, if you want to debug.
   }
 }
 
-\section{
-  \title{\code{fly builds}}{fly-builds}
-
-  To list the most recent builds, run:
-
-  \codeblock{bash}{{
-  $ fly -t example builds
-  }}
-
-  To list the builds of a job, run:
-
-  \codeblock{bash}{{
-  $ fly -t example builds -j pipeline-name/job-name
-  }}
-
-  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
-  the \code{-c} flag, like so:
-
-  \codeblock{bash}{{
-  $ fly -t example builds -c 100
-  }}
-}
-
-\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.
-
-  To this end, there is a \code{fly intercept} command that will give 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.
-
-  For example, running the following will run a task and then enter the
-  finished task's container:
-
-  \codeblock{bash}{{
-  $ fly -t example execute
-  $ fly -t example intercept --step build
-  }}
-
-  \aside{
-    When intercepting a task running on a Windows worker, you will need to
-    specifically tell fly to 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.
-
-  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
-  step from a build of a job in your pipeline. These flags also have short
-  forms, like so:
-
-  \codeblock{bash}{{
-  $ fly -t example intercept -j some-pipeline/some-job -b some-build -s some-step
-  }}
-
-  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.
-
-  The \code{--step} flag can also be omitted; this will let you pick the step
-  interactively, if you don't know the exact name.
-
-  Resource checking containers can also be intercepted with \code{--check} or
-  \code{-c}:
-
-  \codeblock{bash}{{
-  $ fly -t example intercept --check some-pipeline/some-resource
-  }}
-
-  A specific command can also be given, e.g. \code{fly intercept ps auxf} or
-  \code{fly intercept htop}. This allows for patterns such as \code{watch fly
-  intercept ps auxf}, which will continuously show the process tree of the
-  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
-  also be used for the process run by intercept.
-}
-
-\section{
-  \title{\code{fly abort-build}}{fly-abort-build}
-
-  To abort a build of a job, run:
-
-  \codeblock{bash}{{
-  $ fly -t example abort-build --job my-pipeline/my-job --build 3
-  }}
-
-  This will cancel build \code{3} of the \code{my-job} job in the
-  \code{my-pipeline} pipeline.
-}
-
-\section{
-  \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
-  processed by other commands).
-
-  The \code{watch} command can be used to do just this. You can also 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}
-  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
-  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.
-
-  \codeblock{bash}{{
-  $ fly -t example watch --job my-pipeline/tests --build 52
-  }}
-
-  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. 
-}
diff --git a/lit/references/fly.lit b/lit/references/fly.lit
index b3889b74..74d42436 100644
--- a/lit/references/fly.lit
+++ b/lit/references/fly.lit
@@ -35,7 +35,9 @@ to consult \code{fly -h} to learn the short forms.
 
 \include-section{fly/_template.lit}
 
+\include-section{fly/abort-build.lit}
 \include-section{fly/archive-pipeline.lit}
+\include-section{fly/builds.lit}
 \include-section{fly/completion.lit}
 \include-section{fly/delete-target.lit}
 \include-section{fly/destroy-pipeline.lit}
@@ -44,6 +46,7 @@ to consult \code{fly -h} to learn the short forms.
 \include-section{fly/format-pipeline.lit}
 \include-section{fly/get-pipeline.lit}
 \include-section{fly/hide-pipeline.lit}
+\include-section{fly/intercept.lit}
 \include-section{fly/login.lit}
 \include-section{fly/logout.lit}
 \include-section{fly/instance-groups.lit}
@@ -58,3 +61,4 @@ to consult \code{fly -h} to learn the short forms.
 \include-section{fly/unpause-pipeline.lit}
 \include-section{fly/userinfo.lit}
 \include-section{fly/validate-pipeline.lit}
+\include-section{fly/watch.lit}
diff --git a/lit/references/fly/abort-build.lit b/lit/references/fly/abort-build.lit
new file mode 100644
index 00000000..6589ccca
--- /dev/null
+++ b/lit/references/fly/abort-build.lit
@@ -0,0 +1,11 @@
+\title{\code{fly abort-build}}{fly-abort-build}
+\use-plugin{concourse-docs}
+
+To abort a build of a job, run:
+
+\codeblock{bash}{{
+$ fly -t example abort-build --job my-pipeline/my-job --build 3
+}}
+
+This will cancel build \code{3} of the \code{my-job} job in the
+\code{my-pipeline} pipeline.
\ No newline at end of file
diff --git a/lit/references/fly/builds.lit b/lit/references/fly/builds.lit
new file mode 100644
index 00000000..0b4b8a1c
--- /dev/null
+++ b/lit/references/fly/builds.lit
@@ -0,0 +1,24 @@
+\title{\code{fly builds}}{fly-builds}
+\use-plugin{concourse-docs}
+
+To list the most recent builds, run:
+
+\codeblock{bash}{{
+$ fly -t example builds
+}}
+
+To list the builds of a job, run:
+
+\codeblock{bash}{{
+$ fly -t example builds -j pipeline-name/job-name
+}}
+
+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
+the \code{-c} flag, like so:
+
+\codeblock{bash}{{
+$ fly -t example builds -c 100
+}}
\ No newline at end of file
diff --git a/lit/references/fly/intercept.lit b/lit/references/fly/intercept.lit
new file mode 100644
index 00000000..10c69d5a
--- /dev/null
+++ b/lit/references/fly/intercept.lit
@@ -0,0 +1,65 @@
+\title{\code{fly intercept}}{fly-intercept}
+\use-plugin{concourse-docs}
+
+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.
+
+To this end, there is a \code{fly intercept} command that will give 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.
+
+For example, running the following will run a task and then enter the
+finished task's container:
+
+\codeblock{bash}{{
+$ fly -t example execute
+$ fly -t example intercept --step build
+}}
+
+\aside{
+When intercepting a task running on a Windows worker, you will need to
+specifically tell fly to 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.
+
+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
+step from a build of a job in your pipeline. These flags also have short
+forms, like so:
+
+\codeblock{bash}{{
+$ fly -t example intercept -j some-pipeline/some-job -b some-build -s some-step
+}}
+
+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.
+
+The \code{--step} flag can also be omitted; this will let you pick the step
+interactively, if you don't know the exact name.
+
+Resource checking containers can also be intercepted with \code{--check} or
+\code{-c}:
+
+\codeblock{bash}{{
+$ fly -t example intercept --check some-pipeline/some-resource
+}}
+
+A specific command can also be given, e.g. \code{fly intercept ps auxf} or
+\code{fly intercept htop}. This allows for patterns such as \code{watch fly
+intercept ps auxf}, which will continuously show the process tree of the
+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
+also be used for the process run by intercept.
diff --git a/lit/references/fly/watch.lit b/lit/references/fly/watch.lit
new file mode 100644
index 00000000..1c628002
--- /dev/null
+++ b/lit/references/fly/watch.lit
@@ -0,0 +1,33 @@
+\title{\code{fly watch}}{fly-watch}
+\use-plugin{concourse-docs}
+
+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
+processed by other commands).
+
+The \code{watch} command can be used to do just this. You can also 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}
+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
+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.
+
+\codeblock{bash}{{
+$ fly -t example watch --job my-pipeline/tests --build 52
+}}
+
+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. 

From 0b613106c3d4219947b9172e4e1504a24f5e78ae Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:33:49 +0100
Subject: [PATCH 17/26] Move builds from docs into users

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/docs.lit                   | 1 -
 lit/users.lit                  | 1 +
 lit/{docs => users}/builds.lit | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename lit/{docs => users}/builds.lit (100%)

diff --git a/lit/docs.lit b/lit/docs.lit
index 8e924a75..7afea824 100644
--- a/lit/docs.lit
+++ b/lit/docs.lit
@@ -3,7 +3,6 @@
 \use-plugin{concourse-docs}
 
 
-\include-section{./docs/builds.lit}
 \include-section{./docs/how-to-guides.lit}
 
 \split-sections
diff --git a/lit/users.lit b/lit/users.lit
index 06365f7a..61d50876 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -54,4 +54,5 @@ the "big picture" as the mental model sets in.
 
 \include-section{users/install.lit}
 \include-section{users/config.lit}
+\include-section{users/builds.lit}
 \include-section{users/managing-pipelines.lit}
diff --git a/lit/docs/builds.lit b/lit/users/builds.lit
similarity index 100%
rename from lit/docs/builds.lit
rename to lit/users/builds.lit

From 18a1af983fa776e10847af47cfae9fc662c206d3 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:47:05 +0100
Subject: [PATCH 18/26] Move how-to-guides from docs to users

* Remove docs topic completely
* Resolve how to guide and move components into users

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/beginners/getting-started/resources.lit     |  2 --
 lit/docs.lit                                    |  9 ---------
 lit/docs/how-to-guides.lit                      | 14 --------------
 lit/examples.lit                                |  2 +-
 lit/index.lit                                   |  1 -
 lit/users.lit                                   |  3 +++
 lit/{docs/guides => users}/container-images.lit |  0
 lit/{docs/guides => users}/git.lit              |  0
 lit/{docs/guides => users}/pipeline-guides.lit  |  0
 9 files changed, 4 insertions(+), 27 deletions(-)
 delete mode 100644 lit/docs.lit
 delete mode 100644 lit/docs/how-to-guides.lit
 rename lit/{docs/guides => users}/container-images.lit (100%)
 rename lit/{docs/guides => users}/git.lit (100%)
 rename lit/{docs/guides => users}/pipeline-guides.lit (100%)

diff --git a/lit/beginners/getting-started/resources.lit b/lit/beginners/getting-started/resources.lit
index fae7256c..b3ad57cc 100644
--- a/lit/beginners/getting-started/resources.lit
+++ b/lit/beginners/getting-started/resources.lit
@@ -672,8 +672,6 @@
   own. Here are some other parts of the site to help you take off with Concourse:
 
   \list{
-    \reference{how-to-guides} - Contains tips for writing pipelines and examples of common pipeline workflows
-  }{
     Check out all the reference documentation:
     \list{\reference{jobs}}{\reference{tasks}}{\reference{resources}}{\reference{resource-types}}
   }{
diff --git a/lit/docs.lit b/lit/docs.lit
deleted file mode 100644
index 7afea824..00000000
--- a/lit/docs.lit
+++ /dev/null
@@ -1,9 +0,0 @@
-\title{Docs}{docs}
-
-\use-plugin{concourse-docs}
-
-
-\include-section{./docs/how-to-guides.lit}
-
-\split-sections
-\table-of-contents
diff --git a/lit/docs/how-to-guides.lit b/lit/docs/how-to-guides.lit
deleted file mode 100644
index 1df6b22b..00000000
--- a/lit/docs/how-to-guides.lit
+++ /dev/null
@@ -1,14 +0,0 @@
-\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.
-
-\split-sections
-\table-of-contents
-
-\include-section{./guides/pipeline-guides.lit}
-\include-section{./guides/git.lit}
-\include-section{./guides/container-images.lit}
diff --git a/lit/examples.lit b/lit/examples.lit
index c5561cee..153aa93c 100644
--- a/lit/examples.lit
+++ b/lit/examples.lit
@@ -9,7 +9,7 @@ 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}.
+covered in the \reference{users}.
 
 \include-section{./examples/hello-world.lit}
 \include-section{./examples/serial-job.lit}
diff --git a/lit/index.lit b/lit/index.lit
index 75fadcaf..85d9449d 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -197,7 +197,6 @@
 
 \include-section{./beginners.lit}
 \include-section{./users.lit}
-\include-section{./docs.lit}
 \include-section{./examples.lit}
 \include-section{./project.lit}
 \include-section{./ecosystem.lit}
diff --git a/lit/users.lit b/lit/users.lit
index 61d50876..0d52f120 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -56,3 +56,6 @@ the "big picture" as the mental model sets in.
 \include-section{users/config.lit}
 \include-section{users/builds.lit}
 \include-section{users/managing-pipelines.lit}
+\include-section{users/pipeline-guides.lit}
+\include-section{users/git.lit}
+\include-section{users/container-images.lit}
\ No newline at end of file
diff --git a/lit/docs/guides/container-images.lit b/lit/users/container-images.lit
similarity index 100%
rename from lit/docs/guides/container-images.lit
rename to lit/users/container-images.lit
diff --git a/lit/docs/guides/git.lit b/lit/users/git.lit
similarity index 100%
rename from lit/docs/guides/git.lit
rename to lit/users/git.lit
diff --git a/lit/docs/guides/pipeline-guides.lit b/lit/users/pipeline-guides.lit
similarity index 100%
rename from lit/docs/guides/pipeline-guides.lit
rename to lit/users/pipeline-guides.lit

From 0fe387c774023fd40e28fac571fe55ec12743841 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:50:11 +0100
Subject: [PATCH 19/26] Move examples into users

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/index.lit                                    | 1 -
 lit/users.lit                                    | 3 ++-
 lit/{ => users}/examples.lit                     | 0
 lit/{ => users}/examples/attic/dockerhub.lit     | 0
 lit/{ => users}/examples/git-triggered.lit       | 0
 lit/{ => users}/examples/golang-lib.lit          | 0
 lit/{ => users}/examples/hello-world.lit         | 0
 lit/{ => users}/examples/hooks.lit               | 0
 lit/{ => users}/examples/java.lit                | 0
 lit/{ => users}/examples/manual-trigger.lit      | 0
 lit/{ => users}/examples/nodejs.lit              | 0
 lit/{ => users}/examples/php.lit                 | 0
 lit/{ => users}/examples/pipeline-vars.lit       | 0
 lit/{ => users}/examples/rails.lit               | 0
 lit/{ => users}/examples/serial-job.lit          | 0
 lit/{ => users}/examples/set-pipelines.lit       | 0
 lit/{ => users}/examples/task-inputs-outputs.lit | 0
 lit/{ => users}/examples/time-triggered.lit      | 0
 18 files changed, 2 insertions(+), 2 deletions(-)
 rename lit/{ => users}/examples.lit (100%)
 rename lit/{ => users}/examples/attic/dockerhub.lit (100%)
 rename lit/{ => users}/examples/git-triggered.lit (100%)
 rename lit/{ => users}/examples/golang-lib.lit (100%)
 rename lit/{ => users}/examples/hello-world.lit (100%)
 rename lit/{ => users}/examples/hooks.lit (100%)
 rename lit/{ => users}/examples/java.lit (100%)
 rename lit/{ => users}/examples/manual-trigger.lit (100%)
 rename lit/{ => users}/examples/nodejs.lit (100%)
 rename lit/{ => users}/examples/php.lit (100%)
 rename lit/{ => users}/examples/pipeline-vars.lit (100%)
 rename lit/{ => users}/examples/rails.lit (100%)
 rename lit/{ => users}/examples/serial-job.lit (100%)
 rename lit/{ => users}/examples/set-pipelines.lit (100%)
 rename lit/{ => users}/examples/task-inputs-outputs.lit (100%)
 rename lit/{ => users}/examples/time-triggered.lit (100%)

diff --git a/lit/index.lit b/lit/index.lit
index 85d9449d..ab31a485 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -197,7 +197,6 @@
 
 \include-section{./beginners.lit}
 \include-section{./users.lit}
-\include-section{./examples.lit}
 \include-section{./project.lit}
 \include-section{./ecosystem.lit}
 \include-section{./references.lit}
diff --git a/lit/users.lit b/lit/users.lit
index 0d52f120..9f015da3 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -58,4 +58,5 @@ the "big picture" as the mental model sets in.
 \include-section{users/managing-pipelines.lit}
 \include-section{users/pipeline-guides.lit}
 \include-section{users/git.lit}
-\include-section{users/container-images.lit}
\ No newline at end of file
+\include-section{users/container-images.lit}
+\include-section{users/examples.lit}
\ No newline at end of file
diff --git a/lit/examples.lit b/lit/users/examples.lit
similarity index 100%
rename from lit/examples.lit
rename to lit/users/examples.lit
diff --git a/lit/examples/attic/dockerhub.lit b/lit/users/examples/attic/dockerhub.lit
similarity index 100%
rename from lit/examples/attic/dockerhub.lit
rename to lit/users/examples/attic/dockerhub.lit
diff --git a/lit/examples/git-triggered.lit b/lit/users/examples/git-triggered.lit
similarity index 100%
rename from lit/examples/git-triggered.lit
rename to lit/users/examples/git-triggered.lit
diff --git a/lit/examples/golang-lib.lit b/lit/users/examples/golang-lib.lit
similarity index 100%
rename from lit/examples/golang-lib.lit
rename to lit/users/examples/golang-lib.lit
diff --git a/lit/examples/hello-world.lit b/lit/users/examples/hello-world.lit
similarity index 100%
rename from lit/examples/hello-world.lit
rename to lit/users/examples/hello-world.lit
diff --git a/lit/examples/hooks.lit b/lit/users/examples/hooks.lit
similarity index 100%
rename from lit/examples/hooks.lit
rename to lit/users/examples/hooks.lit
diff --git a/lit/examples/java.lit b/lit/users/examples/java.lit
similarity index 100%
rename from lit/examples/java.lit
rename to lit/users/examples/java.lit
diff --git a/lit/examples/manual-trigger.lit b/lit/users/examples/manual-trigger.lit
similarity index 100%
rename from lit/examples/manual-trigger.lit
rename to lit/users/examples/manual-trigger.lit
diff --git a/lit/examples/nodejs.lit b/lit/users/examples/nodejs.lit
similarity index 100%
rename from lit/examples/nodejs.lit
rename to lit/users/examples/nodejs.lit
diff --git a/lit/examples/php.lit b/lit/users/examples/php.lit
similarity index 100%
rename from lit/examples/php.lit
rename to lit/users/examples/php.lit
diff --git a/lit/examples/pipeline-vars.lit b/lit/users/examples/pipeline-vars.lit
similarity index 100%
rename from lit/examples/pipeline-vars.lit
rename to lit/users/examples/pipeline-vars.lit
diff --git a/lit/examples/rails.lit b/lit/users/examples/rails.lit
similarity index 100%
rename from lit/examples/rails.lit
rename to lit/users/examples/rails.lit
diff --git a/lit/examples/serial-job.lit b/lit/users/examples/serial-job.lit
similarity index 100%
rename from lit/examples/serial-job.lit
rename to lit/users/examples/serial-job.lit
diff --git a/lit/examples/set-pipelines.lit b/lit/users/examples/set-pipelines.lit
similarity index 100%
rename from lit/examples/set-pipelines.lit
rename to lit/users/examples/set-pipelines.lit
diff --git a/lit/examples/task-inputs-outputs.lit b/lit/users/examples/task-inputs-outputs.lit
similarity index 100%
rename from lit/examples/task-inputs-outputs.lit
rename to lit/users/examples/task-inputs-outputs.lit
diff --git a/lit/examples/time-triggered.lit b/lit/users/examples/time-triggered.lit
similarity index 100%
rename from lit/examples/time-triggered.lit
rename to lit/users/examples/time-triggered.lit

From f2a83f28e2f7d8c616decb92c16a79ac5af67d34 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:52:11 +0100
Subject: [PATCH 20/26] Move project into users

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/index.lit               | 1 -
 lit/users.lit               | 3 ++-
 lit/{ => users}/project.lit | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename lit/{ => users}/project.lit (100%)

diff --git a/lit/index.lit b/lit/index.lit
index ab31a485..a117430b 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -197,6 +197,5 @@
 
 \include-section{./beginners.lit}
 \include-section{./users.lit}
-\include-section{./project.lit}
 \include-section{./ecosystem.lit}
 \include-section{./references.lit}
diff --git a/lit/users.lit b/lit/users.lit
index 9f015da3..16e71870 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -59,4 +59,5 @@ the "big picture" as the mental model sets in.
 \include-section{users/pipeline-guides.lit}
 \include-section{users/git.lit}
 \include-section{users/container-images.lit}
-\include-section{users/examples.lit}
\ No newline at end of file
+\include-section{users/examples.lit}
+\include-section{users/project.lit}
\ No newline at end of file
diff --git a/lit/project.lit b/lit/users/project.lit
similarity index 100%
rename from lit/project.lit
rename to lit/users/project.lit

From fdcc10a3ffba173d473abab053831e99627db66a Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:57:07 +0100
Subject: [PATCH 21/26] Move ecosystem into users

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/index.lit                 | 1 -
 lit/users.lit                 | 3 ++-
 lit/{ => users}/ecosystem.lit | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename lit/{ => users}/ecosystem.lit (100%)

diff --git a/lit/index.lit b/lit/index.lit
index a117430b..44cb806b 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -197,5 +197,4 @@
 
 \include-section{./beginners.lit}
 \include-section{./users.lit}
-\include-section{./ecosystem.lit}
 \include-section{./references.lit}
diff --git a/lit/users.lit b/lit/users.lit
index 16e71870..ecee34e5 100644
--- a/lit/users.lit
+++ b/lit/users.lit
@@ -60,4 +60,5 @@ the "big picture" as the mental model sets in.
 \include-section{users/git.lit}
 \include-section{users/container-images.lit}
 \include-section{users/examples.lit}
-\include-section{users/project.lit}
\ No newline at end of file
+\include-section{users/project.lit}
+\include-section{users/ecosystem.lit}
\ No newline at end of file
diff --git a/lit/ecosystem.lit b/lit/users/ecosystem.lit
similarity index 100%
rename from lit/ecosystem.lit
rename to lit/users/ecosystem.lit

From ae48069bd5dd0170d39d990760514f080766353d Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Thu, 3 Feb 2022 15:59:13 +0100
Subject: [PATCH 22/26] Prepare (empty) admin topic

This is disabled ATM, but if needed it can be enabled
at any time.

Signed-off-by: Tom Schraitle <tom_schr@web.de>
---
 lit/admins.lit | 5 +++++
 lit/index.lit  | 4 ++++
 2 files changed, 9 insertions(+)
 create mode 100644 lit/admins.lit

diff --git a/lit/admins.lit b/lit/admins.lit
new file mode 100644
index 00000000..29d44f92
--- /dev/null
+++ b/lit/admins.lit
@@ -0,0 +1,5 @@
+\title{Admins}{admins}
+
+\use-plugin{concourse-docs}
+
+Lists tasks for administrators
diff --git a/lit/index.lit b/lit/index.lit
index 44cb806b..c2e37a98 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -188,13 +188,17 @@
     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.
 
+{-
     To see what resource types are available, check out the \link{Resource Types
     catalog}{https://resource-types.concourse-ci.org}!
+-}
   }
 }
 
 \split-sections
 
 \include-section{./beginners.lit}
+{- \include-section{./admins.lit} -}
 \include-section{./users.lit}
+
 \include-section{./references.lit}

From 8e6655efc2bce2ea133a3fbef550a36c23cae7c1 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Mon, 7 Feb 2022 09:16:36 +0100
Subject: [PATCH 23/26] Use "Start" instead of "Beginners"

---
 lit/beginners.lit                                          | 7 -------
 lit/index.lit                                              | 2 +-
 lit/start.lit                                              | 7 +++++++
 lit/{beginners => start}/getting-started.lit               | 0
 lit/{beginners => start}/getting-started/hello-world.lit   | 0
 .../getting-started/inputs-outputs.lit                     | 0
 lit/{beginners => start}/getting-started/quickstart.lit    | 0
 lit/{beginners => start}/getting-started/resources.lit     | 0
 lit/{beginners => start}/whats-next.lit                    | 0
 9 files changed, 8 insertions(+), 8 deletions(-)
 delete mode 100644 lit/beginners.lit
 create mode 100644 lit/start.lit
 rename lit/{beginners => start}/getting-started.lit (100%)
 rename lit/{beginners => start}/getting-started/hello-world.lit (100%)
 rename lit/{beginners => start}/getting-started/inputs-outputs.lit (100%)
 rename lit/{beginners => start}/getting-started/quickstart.lit (100%)
 rename lit/{beginners => start}/getting-started/resources.lit (100%)
 rename lit/{beginners => start}/whats-next.lit (100%)

diff --git a/lit/beginners.lit b/lit/beginners.lit
deleted file mode 100644
index 2bcff6ad..00000000
--- a/lit/beginners.lit
+++ /dev/null
@@ -1,7 +0,0 @@
-\title{Beginners}
-
-\use-plugin{concourse-docs}
-
-
-\include-section{./beginners/getting-started.lit}
-\include-section{./beginners/whats-next.lit}
\ No newline at end of file
diff --git a/lit/index.lit b/lit/index.lit
index c2e37a98..8e63838b 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -197,7 +197,7 @@
 
 \split-sections
 
-\include-section{./beginners.lit}
+\include-section{./start.lit}
 {- \include-section{./admins.lit} -}
 \include-section{./users.lit}
 
diff --git a/lit/start.lit b/lit/start.lit
new file mode 100644
index 00000000..28946618
--- /dev/null
+++ b/lit/start.lit
@@ -0,0 +1,7 @@
+\title{Start}
+
+\use-plugin{concourse-docs}
+
+
+\include-section{./start/getting-started.lit}
+\include-section{./start/whats-next.lit}
\ No newline at end of file
diff --git a/lit/beginners/getting-started.lit b/lit/start/getting-started.lit
similarity index 100%
rename from lit/beginners/getting-started.lit
rename to lit/start/getting-started.lit
diff --git a/lit/beginners/getting-started/hello-world.lit b/lit/start/getting-started/hello-world.lit
similarity index 100%
rename from lit/beginners/getting-started/hello-world.lit
rename to lit/start/getting-started/hello-world.lit
diff --git a/lit/beginners/getting-started/inputs-outputs.lit b/lit/start/getting-started/inputs-outputs.lit
similarity index 100%
rename from lit/beginners/getting-started/inputs-outputs.lit
rename to lit/start/getting-started/inputs-outputs.lit
diff --git a/lit/beginners/getting-started/quickstart.lit b/lit/start/getting-started/quickstart.lit
similarity index 100%
rename from lit/beginners/getting-started/quickstart.lit
rename to lit/start/getting-started/quickstart.lit
diff --git a/lit/beginners/getting-started/resources.lit b/lit/start/getting-started/resources.lit
similarity index 100%
rename from lit/beginners/getting-started/resources.lit
rename to lit/start/getting-started/resources.lit
diff --git a/lit/beginners/whats-next.lit b/lit/start/whats-next.lit
similarity index 100%
rename from lit/beginners/whats-next.lit
rename to lit/start/whats-next.lit

From 3971d518f1bbd2b06302c40adb7ebd9fa0f1bdcb Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Mon, 7 Feb 2022 09:21:38 +0100
Subject: [PATCH 24/26] Use "guides" instead of "users"

---
 lit/{users.lit => guides.lit}                 | 22 +++++++++----------
 lit/{users => guides}/builds.lit              |  0
 lit/{users => guides}/config.lit              |  0
 .../config/basic-schemas.lit                  |  0
 lit/{users => guides}/config/vars/caching.lit |  0
 lit/{users => guides}/config/yaml.lit         |  0
 lit/{users => guides}/container-images.lit    |  0
 lit/{users => guides}/ecosystem.lit           |  0
 lit/{users => guides}/examples.lit            |  2 +-
 .../examples/attic/dockerhub.lit              |  0
 .../examples/git-triggered.lit                |  0
 lit/{users => guides}/examples/golang-lib.lit |  0
 .../examples/hello-world.lit                  |  0
 lit/{users => guides}/examples/hooks.lit      |  0
 lit/{users => guides}/examples/java.lit       |  0
 .../examples/manual-trigger.lit               |  0
 lit/{users => guides}/examples/nodejs.lit     |  0
 lit/{users => guides}/examples/php.lit        |  0
 .../examples/pipeline-vars.lit                |  0
 lit/{users => guides}/examples/rails.lit      |  0
 lit/{users => guides}/examples/serial-job.lit |  0
 .../examples/set-pipelines.lit                |  0
 .../examples/task-inputs-outputs.lit          |  0
 .../examples/time-triggered.lit               |  0
 lit/{users => guides}/git.lit                 |  0
 lit/{users => guides}/install.lit             |  0
 .../install/concourse-cli.lit                 |  0
 lit/{users => guides}/install/db.lit          |  0
 .../install/generating-keys.lit               |  0
 lit/{users => guides}/install/upgrading.lit   |  0
 lit/{users => guides}/install/web.lit         |  0
 lit/{users => guides}/install/worker.lit      |  0
 lit/{users => guides}/managing-pipelines.lit  |  0
 lit/{users => guides}/pipeline-guides.lit     |  0
 lit/{users => guides}/project.lit             |  0
 lit/index.lit                                 |  5 ++---
 36 files changed, 14 insertions(+), 15 deletions(-)
 rename lit/{users.lit => guides.lit} (85%)
 rename lit/{users => guides}/builds.lit (100%)
 rename lit/{users => guides}/config.lit (100%)
 rename lit/{users => guides}/config/basic-schemas.lit (100%)
 rename lit/{users => guides}/config/vars/caching.lit (100%)
 rename lit/{users => guides}/config/yaml.lit (100%)
 rename lit/{users => guides}/container-images.lit (100%)
 rename lit/{users => guides}/ecosystem.lit (100%)
 rename lit/{users => guides}/examples.lit (97%)
 rename lit/{users => guides}/examples/attic/dockerhub.lit (100%)
 rename lit/{users => guides}/examples/git-triggered.lit (100%)
 rename lit/{users => guides}/examples/golang-lib.lit (100%)
 rename lit/{users => guides}/examples/hello-world.lit (100%)
 rename lit/{users => guides}/examples/hooks.lit (100%)
 rename lit/{users => guides}/examples/java.lit (100%)
 rename lit/{users => guides}/examples/manual-trigger.lit (100%)
 rename lit/{users => guides}/examples/nodejs.lit (100%)
 rename lit/{users => guides}/examples/php.lit (100%)
 rename lit/{users => guides}/examples/pipeline-vars.lit (100%)
 rename lit/{users => guides}/examples/rails.lit (100%)
 rename lit/{users => guides}/examples/serial-job.lit (100%)
 rename lit/{users => guides}/examples/set-pipelines.lit (100%)
 rename lit/{users => guides}/examples/task-inputs-outputs.lit (100%)
 rename lit/{users => guides}/examples/time-triggered.lit (100%)
 rename lit/{users => guides}/git.lit (100%)
 rename lit/{users => guides}/install.lit (100%)
 rename lit/{users => guides}/install/concourse-cli.lit (100%)
 rename lit/{users => guides}/install/db.lit (100%)
 rename lit/{users => guides}/install/generating-keys.lit (100%)
 rename lit/{users => guides}/install/upgrading.lit (100%)
 rename lit/{users => guides}/install/web.lit (100%)
 rename lit/{users => guides}/install/worker.lit (100%)
 rename lit/{users => guides}/managing-pipelines.lit (100%)
 rename lit/{users => guides}/pipeline-guides.lit (100%)
 rename lit/{users => guides}/project.lit (100%)

diff --git a/lit/users.lit b/lit/guides.lit
similarity index 85%
rename from lit/users.lit
rename to lit/guides.lit
index ecee34e5..b374d082 100644
--- a/lit/users.lit
+++ b/lit/guides.lit
@@ -1,4 +1,4 @@
-\title{Users}{users}
+\title{Guides}{guides}
 \use-plugin{concourse-docs}
 \split-sections
 
@@ -52,13 +52,13 @@ the "big picture" as the mental model sets in.
 
 }
 
-\include-section{users/install.lit}
-\include-section{users/config.lit}
-\include-section{users/builds.lit}
-\include-section{users/managing-pipelines.lit}
-\include-section{users/pipeline-guides.lit}
-\include-section{users/git.lit}
-\include-section{users/container-images.lit}
-\include-section{users/examples.lit}
-\include-section{users/project.lit}
-\include-section{users/ecosystem.lit}
\ No newline at end of file
+\include-section{guides/install.lit}
+\include-section{guides/config.lit}
+\include-section{guides/builds.lit}
+\include-section{guides/managing-pipelines.lit}
+\include-section{guides/pipeline-guides.lit}
+\include-section{guides/git.lit}
+\include-section{guides/container-images.lit}
+\include-section{guides/examples.lit}
+\include-section{guides/project.lit}
+\include-section{guides/ecosystem.lit}
\ No newline at end of file
diff --git a/lit/users/builds.lit b/lit/guides/builds.lit
similarity index 100%
rename from lit/users/builds.lit
rename to lit/guides/builds.lit
diff --git a/lit/users/config.lit b/lit/guides/config.lit
similarity index 100%
rename from lit/users/config.lit
rename to lit/guides/config.lit
diff --git a/lit/users/config/basic-schemas.lit b/lit/guides/config/basic-schemas.lit
similarity index 100%
rename from lit/users/config/basic-schemas.lit
rename to lit/guides/config/basic-schemas.lit
diff --git a/lit/users/config/vars/caching.lit b/lit/guides/config/vars/caching.lit
similarity index 100%
rename from lit/users/config/vars/caching.lit
rename to lit/guides/config/vars/caching.lit
diff --git a/lit/users/config/yaml.lit b/lit/guides/config/yaml.lit
similarity index 100%
rename from lit/users/config/yaml.lit
rename to lit/guides/config/yaml.lit
diff --git a/lit/users/container-images.lit b/lit/guides/container-images.lit
similarity index 100%
rename from lit/users/container-images.lit
rename to lit/guides/container-images.lit
diff --git a/lit/users/ecosystem.lit b/lit/guides/ecosystem.lit
similarity index 100%
rename from lit/users/ecosystem.lit
rename to lit/guides/ecosystem.lit
diff --git a/lit/users/examples.lit b/lit/guides/examples.lit
similarity index 97%
rename from lit/users/examples.lit
rename to lit/guides/examples.lit
index 153aa93c..58a36d63 100644
--- a/lit/users/examples.lit
+++ b/lit/guides/examples.lit
@@ -9,7 +9,7 @@ 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{users}.
+covered in the \reference{guides}.
 
 \include-section{./examples/hello-world.lit}
 \include-section{./examples/serial-job.lit}
diff --git a/lit/users/examples/attic/dockerhub.lit b/lit/guides/examples/attic/dockerhub.lit
similarity index 100%
rename from lit/users/examples/attic/dockerhub.lit
rename to lit/guides/examples/attic/dockerhub.lit
diff --git a/lit/users/examples/git-triggered.lit b/lit/guides/examples/git-triggered.lit
similarity index 100%
rename from lit/users/examples/git-triggered.lit
rename to lit/guides/examples/git-triggered.lit
diff --git a/lit/users/examples/golang-lib.lit b/lit/guides/examples/golang-lib.lit
similarity index 100%
rename from lit/users/examples/golang-lib.lit
rename to lit/guides/examples/golang-lib.lit
diff --git a/lit/users/examples/hello-world.lit b/lit/guides/examples/hello-world.lit
similarity index 100%
rename from lit/users/examples/hello-world.lit
rename to lit/guides/examples/hello-world.lit
diff --git a/lit/users/examples/hooks.lit b/lit/guides/examples/hooks.lit
similarity index 100%
rename from lit/users/examples/hooks.lit
rename to lit/guides/examples/hooks.lit
diff --git a/lit/users/examples/java.lit b/lit/guides/examples/java.lit
similarity index 100%
rename from lit/users/examples/java.lit
rename to lit/guides/examples/java.lit
diff --git a/lit/users/examples/manual-trigger.lit b/lit/guides/examples/manual-trigger.lit
similarity index 100%
rename from lit/users/examples/manual-trigger.lit
rename to lit/guides/examples/manual-trigger.lit
diff --git a/lit/users/examples/nodejs.lit b/lit/guides/examples/nodejs.lit
similarity index 100%
rename from lit/users/examples/nodejs.lit
rename to lit/guides/examples/nodejs.lit
diff --git a/lit/users/examples/php.lit b/lit/guides/examples/php.lit
similarity index 100%
rename from lit/users/examples/php.lit
rename to lit/guides/examples/php.lit
diff --git a/lit/users/examples/pipeline-vars.lit b/lit/guides/examples/pipeline-vars.lit
similarity index 100%
rename from lit/users/examples/pipeline-vars.lit
rename to lit/guides/examples/pipeline-vars.lit
diff --git a/lit/users/examples/rails.lit b/lit/guides/examples/rails.lit
similarity index 100%
rename from lit/users/examples/rails.lit
rename to lit/guides/examples/rails.lit
diff --git a/lit/users/examples/serial-job.lit b/lit/guides/examples/serial-job.lit
similarity index 100%
rename from lit/users/examples/serial-job.lit
rename to lit/guides/examples/serial-job.lit
diff --git a/lit/users/examples/set-pipelines.lit b/lit/guides/examples/set-pipelines.lit
similarity index 100%
rename from lit/users/examples/set-pipelines.lit
rename to lit/guides/examples/set-pipelines.lit
diff --git a/lit/users/examples/task-inputs-outputs.lit b/lit/guides/examples/task-inputs-outputs.lit
similarity index 100%
rename from lit/users/examples/task-inputs-outputs.lit
rename to lit/guides/examples/task-inputs-outputs.lit
diff --git a/lit/users/examples/time-triggered.lit b/lit/guides/examples/time-triggered.lit
similarity index 100%
rename from lit/users/examples/time-triggered.lit
rename to lit/guides/examples/time-triggered.lit
diff --git a/lit/users/git.lit b/lit/guides/git.lit
similarity index 100%
rename from lit/users/git.lit
rename to lit/guides/git.lit
diff --git a/lit/users/install.lit b/lit/guides/install.lit
similarity index 100%
rename from lit/users/install.lit
rename to lit/guides/install.lit
diff --git a/lit/users/install/concourse-cli.lit b/lit/guides/install/concourse-cli.lit
similarity index 100%
rename from lit/users/install/concourse-cli.lit
rename to lit/guides/install/concourse-cli.lit
diff --git a/lit/users/install/db.lit b/lit/guides/install/db.lit
similarity index 100%
rename from lit/users/install/db.lit
rename to lit/guides/install/db.lit
diff --git a/lit/users/install/generating-keys.lit b/lit/guides/install/generating-keys.lit
similarity index 100%
rename from lit/users/install/generating-keys.lit
rename to lit/guides/install/generating-keys.lit
diff --git a/lit/users/install/upgrading.lit b/lit/guides/install/upgrading.lit
similarity index 100%
rename from lit/users/install/upgrading.lit
rename to lit/guides/install/upgrading.lit
diff --git a/lit/users/install/web.lit b/lit/guides/install/web.lit
similarity index 100%
rename from lit/users/install/web.lit
rename to lit/guides/install/web.lit
diff --git a/lit/users/install/worker.lit b/lit/guides/install/worker.lit
similarity index 100%
rename from lit/users/install/worker.lit
rename to lit/guides/install/worker.lit
diff --git a/lit/users/managing-pipelines.lit b/lit/guides/managing-pipelines.lit
similarity index 100%
rename from lit/users/managing-pipelines.lit
rename to lit/guides/managing-pipelines.lit
diff --git a/lit/users/pipeline-guides.lit b/lit/guides/pipeline-guides.lit
similarity index 100%
rename from lit/users/pipeline-guides.lit
rename to lit/guides/pipeline-guides.lit
diff --git a/lit/users/project.lit b/lit/guides/project.lit
similarity index 100%
rename from lit/users/project.lit
rename to lit/guides/project.lit
diff --git a/lit/index.lit b/lit/index.lit
index 8e63838b..55b4ba97 100644
--- a/lit/index.lit
+++ b/lit/index.lit
@@ -198,7 +198,6 @@
 \split-sections
 
 \include-section{./start.lit}
-{- \include-section{./admins.lit} -}
-\include-section{./users.lit}
-
+\include-section{./guides.lit}
+\include-section{./concepts.lit}
 \include-section{./references.lit}

From 8aeaff02f90b3bbe1088a97e281f45499ffa5847 Mon Sep 17 00:00:00 2001
From: Tom Schraitle <tom_schr@web.de>
Date: Mon, 7 Feb 2022 09:28:45 +0100
Subject: [PATCH 25/26] Use "concepts"

---
 lit/admins.lit   | 5 -----
 lit/concepts.lit | 5 +++++
 2 files changed, 5 insertions(+), 5 deletions(-)
 delete mode 100644 lit/admins.lit
 create mode 100644 lit/concepts.lit

diff --git a/lit/admins.lit b/lit/admins.lit
deleted file mode 100644
index 29d44f92..00000000
--- a/lit/admins.lit
+++ /dev/null
@@ -1,5 +0,0 @@
-\title{Admins}{admins}
-
-\use-plugin{concourse-docs}
-
-Lists tasks for administrators
diff --git a/lit/concepts.lit b/lit/concepts.lit
new file mode 100644
index 00000000..76fae869
--- /dev/null
+++ b/lit/concepts.lit
@@ -0,0 +1,5 @@
+\title{Concepts}{concepts}
+
+\use-plugin{concourse-docs}
+
+Lists of concepts.

From 75ca5e27ff208334a25da6026a74a43b6cb2e72b Mon Sep 17 00:00:00 2001
From: Taylor Silva <tasilva@vmware.com>
Date: Mon, 7 Feb 2022 12:47:55 -0500
Subject: [PATCH 26/26] Create page about web ui

Signed-off-by: Taylor Silva <tasilva@vmware.com>
---
 images/web-ui/web-ui-dashboard.png         | Bin 0 -> 226903 bytes
 images/web-ui/web-ui-high-density.png      | Bin 0 -> 290128 bytes
 images/web-ui/web-ui-job-build-logs.png    | Bin 0 -> 246062 bytes
 images/web-ui/web-ui-pipeline-overview.png | Bin 0 -> 644741 bytes
 images/web-ui/web-ui-resource-details.png  | Bin 0 -> 296935 bytes
 lit/references.lit                         |   1 +
 lit/references/web-ui.lit                  |  59 +++++++++++++++++++++
 7 files changed, 60 insertions(+)
 create mode 100644 images/web-ui/web-ui-dashboard.png
 create mode 100644 images/web-ui/web-ui-high-density.png
 create mode 100644 images/web-ui/web-ui-job-build-logs.png
 create mode 100644 images/web-ui/web-ui-pipeline-overview.png
 create mode 100644 images/web-ui/web-ui-resource-details.png
 create mode 100644 lit/references/web-ui.lit

diff --git a/images/web-ui/web-ui-dashboard.png b/images/web-ui/web-ui-dashboard.png
new file mode 100644
index 0000000000000000000000000000000000000000..1716e477985ba0412893e7640c7ea342ff29f423
GIT binary patch
diff --git a/images/web-ui/web-ui-high-density.png b/images/web-ui/web-ui-high-density.png
new file mode 100644
index 0000000000000000000000000000000000000000..6842b141c369a19f9c8f254c49637952eb9f04a6
GIT binary patch
diff --git a/images/web-ui/web-ui-job-build-logs.png b/images/web-ui/web-ui-job-build-logs.png
new file mode 100644
index 0000000000000000000000000000000000000000..0503acf25a358031dec5c641e8581c029e7ec9fa
GIT binary patch
diff --git a/images/web-ui/web-ui-pipeline-overview.png b/images/web-ui/web-ui-pipeline-overview.png
new file mode 100644
index 0000000000000000000000000000000000000000..35f6cb1c70b08a461ee1e625b4f395791313a12f
GIT binary patch
diff --git a/images/web-ui/web-ui-resource-details.png b/images/web-ui/web-ui-resource-details.png
new file mode 100644
index 0000000000000000000000000000000000000000..f6663d422de942c4472eba2cf237bf3d82b5730d
GIT binary patch
diff --git a/lit/references.lit b/lit/references.lit
index 637fd670..e3e7f023 100644
--- a/lit/references.lit
+++ b/lit/references.lit
@@ -15,6 +15,7 @@ Contains a reference of:
 -}
 
 \include-section{./references/fly.lit}
+\include-section{./references/web-ui.lit}
 \include-section{./references/resources.lit}
 \include-section{./references/resource-types.lit}
 \include-section{./references/vars.lit}
diff --git a/lit/references/web-ui.lit b/lit/references/web-ui.lit
new file mode 100644
index 00000000..4a2dd51f
--- /dev/null
+++ b/lit/references/web-ui.lit
@@ -0,0 +1,59 @@
+\title{Web UI}{web-ui}
+
+\use-plugin{concourse-docs}
+
+TODO: image of dashboard
+
+\section{
+\title{Purpose}
+  The purpose of the Web UI is to provide an easy to understand, (mostly)
+  read-only view of the state of all your pipelines.
+}
+
+\section{
+\title{Views}
+
+  \section{
+  \title{Dashboard}
+    TODO: using search bar to filter, switching to high density view, favoriting pipelines
+    \link{\diagram{images/web-ui/web-ui-dashboard.png}{100%}}{images/web-ui/web-ui-dashboard.png}
+    High-density view:
+    \link{\diagram{images/web-ui/web-ui-high-density.png}{100%}}{images/web-ui/web-ui-high-density.png}
+  }
+
+  \section{
+  \title{Pipeline Overview}
+    TODO: page that shows pipeline and groups within the pipeline
+    \link{\diagram{images/web-ui/web-ui-pipeline-overview.png}{100%}}{images/web-ui/web-ui-pipeline-overview.png}
+  }
+
+  \section{
+  \title{Build Logs}
+    TODO: page that shows logs for builds
+    \link{\diagram{images/web-ui/web-ui-job-build-logs.png}{100%}}{images/web-ui/web-ui-job-build-logs.png}
+  }
+
+  \section{
+  \title{Resource Versions}{web-view-resource-versions}
+    TODO: page that shows versions of a resource. Where you can pin or disable a version
+    \link{\diagram{images/web-ui/web-ui-resource-details.png}{100%}}{images/web-ui/web-ui-resource-details.png}
+  }
+}
+
+\section{
+\title{Actions You Can Take}
+  Even though the Web UI is mostly read-only, there are the actions you can do
+  from the Web UI.
+
+  \list{
+    Pause/Unpause \reference{pipelines} and/or \reference{jobs}
+  }{
+    Trigger \reference{jobs}
+  }{
+    Trigger a resource check
+  }{
+    Pin or disable a resource version
+  }{
+    Comment on a build
+  }
+}
