docs: Update README for the repository itself r/1669

Adds a lot more information about what is actually going on here, as
well as links to relevant things such as our Monorepo document.

I'm aware that I didn't make all `//...` links clickable, but I
realised at some point that it might be easier to just update cheddar
to support highlighting those natively :-)

Change-Id: Icbb212a6c07a5cf38ab8e65d83a64bec783eb8d0
Reviewed-on: https://cl.tvl.fyi/c/depot/+/1768
Tested-by: BuildkiteCI
Reviewed-by: isomer <isomer@tvl.fyi>
Reviewed-by: kanepyork <rikingcoding@gmail.com>

2 files changed, 7 insertions, 5 deletions

diff --git a/ops/besadii/default.nix b/ops/besadii/default.nix
index 91d6bba6ac..0ce773c7b1 100644
--- a/ops/besadii/default.nix
+++ b/ops/besadii/default.nix
@@ -1,5 +1,5 @@
-# This program is used as a git post-update hook to trigger builds on
-# sourcehut.
+# This program is used as a Gerrit hook to trigger builds on
+# Buildkite, Sourcegraph reindexing and other maintenance tasks.
 { ciBuilds, depot, ... }:
 
 let
diff --git a/ops/pipelines/README.md b/ops/pipelines/README.md
index f4ab1cc1ae..a3f94fd231 100644
--- a/ops/pipelines/README.md
+++ b/ops/pipelines/README.md
@@ -1,3 +1,5 @@
-This folder contains various utilities used for our [Buildkite CI
-setup][ci]. These are mostly hooks invoked by Buildkite runners, or
-configuration used to set up the build pipelines.
+This folder contains the dynamic configuration for our [Buildkite CI
+setup](https://tvl.fyi/builds).
+
+The configuration is built and dynamically loaded by Buildkite at the start of
+each CI pipeline.