document pipeline from the perspective of ocaml.org

README.md

@@ -1,12 +1,13 @@
 # Voodoo
 
-Voodoo is the OCaml documentation generator.
+Voodoo is the OCaml package documentation generator.
 
-## Getting started
+The documentation pipeline at [ocaml-docs-ci](https://github.com/ocurrent/ocaml-docs-ci) uses voodoo to generate data for the ocaml.org website. Read more about how to deploy a new version of voodoo to the documentation pipeline [here](#the-documentation-pipeline).
+
+## Build and run locally
 
 This package is intended to be used as part of an
-[ocurrent](https://github.com/ocurrent/ocurrent) pipeline, for example
-via [ocaml-docs-ci](https://github.com/ocurrent/ocaml-docs-ci). As such,
+[ocurrent](https://github.com/ocurrent/ocurrent) pipeline. As such,
 it's tricky to use in isolation.
 
 Having said that, there is some rudimentary support for using it this way. The steps below will guide you to build to build a small documentation website locally.
@@ -127,3 +128,28 @@ make odoc
 1. Serve `_generated/html`
 
 `voodoo-*` commands must be called from the `_generated` directory.
+
+## The documentation pipeline
+
+The documentation pipeline serves the package documentation built by voodoo at two locations:
+1. live: `https://docs-data.ocaml.org/live/p/{PACKAGE_NAME}/{PACKAGE_VERSION}/` (manually-promoted live version), and
+2. current: `https://docs-data.ocaml.org/current/p/{PACKAGE_NAME}/{PACKAGE_VERSION}/` (always follows the `live` branch of `voodoo`).
+
+The pipeline checks daily for updates to the `live` branch of this repository. When it finds new commits, the pipeline starts to build the package documentation using the new commits. It takes around 24-48h to complete the build. The resulting data appears in the `current` folder.
+
+### Promoting package documentation to live
+
+When all packages' documentation has been built, a job where an [authorized user](https://github.com/ocurrent/ocaml-docs-ci/blob/main/src/ocaml_docs_ci.ml) can manually confirm promoting the `current` folder to the `live` folder appears [here](https://docs.ci.ocaml.org/jobs). 
+
+### How to safely and seamlessly upgrade ocaml.org on breaking changes
+
+If there is a breaking change (usually: modification of the documentation format generated by voodoo),
+we can perform a seamless update on ocaml.org using these steps:
+
+1. push the voodoo update that introduces the breaking change to the `live` branch of voodoo
+2. confirm voodoo update in docs ci
+3. wait 24-48h for the documentation pipeline to build the new package documentation
+4. update ocaml.org to consume data from `https://docs-data.ocaml.org/current` (if necessary, we can fall back to `https://docs-data.ocaml.org/live` which still serves the previous data)
+5. confirm that everything went fine on ocaml.org
+6. [promote the `current` folder to `live`](#promoting-package-documentation-to-live)
+7. update ocaml.org to consume data in the live namespace `https://docs-data.ocaml.org/live`