Status: draft Docs WG position, incomplete — covers what is known as of 2026-10-10.
Who changes the Cloud Foundry docs, who else depends on them, and what each group needs. Needs are given as requirement IDs from the requirement list, such as “R-15 URL identifies the source”.
The RFC is cloudfoundry/community#1642, the draft request for comments that proposes the new docs stack; quotes from it link to their line, as in L112 (glossary).
This page does not say which working group owns which part of the docs. A working group is one of the Cloud Foundry community’s standing teams, each with a charter. Mapping areas to owners is the inventory the RFC asks for in its first phase (L112, L114), and is not done yet.
Terms used below:
bosh.io/docs.docs.cloudfoundry.org, the RFC’s “Phase 4: Cutover and Decommission”
(L133).Each audience, whether it changes the docs, and its main needs:
The Docs WG is the working group for the Cloud Foundry docs. Its
charter
lists in its scope “Merge and edit all doc changes” and
“Maintain internal consistency of doc style, including Notes and
tables…”. Today the Docs WG lead and the
approvers can merge. The book’s CODEOWNERS file assigns every path to one team,
@cloudfoundry/wg-app-runtime-platform-docs-approvers. The book’s
README
still names only the lead: “Only the CFF Docs WG lead can merge pull
requests, build to staging, and publish the documentation.” (CFF is the
Cloud Foundry Foundation; the book is the configuration that collects the
content repositories into one site.)
Needs:
The RFC’s proof of concept is to “Gather feedback from at least three active CF documentation contributors” (L125). The Docs WG lead asked to be one of them, in a comment on the non-public pre-review.
Working groups that own documentation areas review changes to them. The RFC
assigns each area to a working group’s GitHub team through a CODEOWNERS
file, a GitHub file that names who must review changes to which paths
(L75). The Docs WG charter excludes one kind of content from its own
responsibility: “Be responsible for component level documentation (e.g.
Cloud Controller v3 docs)” is listed under Non-Goals, so that content belongs
to the teams that build the components.
Needs:
Anyone who opens a pull request to fix a page: a typo, a changed command, an outdated step.
Needs:
docs.cloudfoundry.org/adminguide/metadata.html
is metadata.html.md.erb in docs-cf-admin, because the book’s
config.yml maps the adminguide
directory to that repository. A
contributor finds the file from the address bar.UAA (the Cloud Foundry login and token service, in the project’s own
description: its
README) and CredHub (the credential store deployed
with BOSH, in the project’s own description: its README) publish API reference docs
built from their code, not from the book. The UAA API docs live in the
cloudfoundry/uaa repository and are built with Slate, a generator for
one-page API references (glossary), from examples
that Spring REST Docs writes while the API tests run
(glossary); the
Gradle build runs those tests, then
the Slate build. CredHub also uses Spring REST Docs, with Asciidoctor
(Gradle build). CredHub’s
prose pages in its own
docs/
folder are separate from the book’s docs-credhub repository.
The CredHub API reference site is built in its own repository,
credhub-api-site,
which the FI WG owns
(charter L80).
Its build script
combines two sources: hand-written docs for the CLI and older server
versions, kept as branches of cloudfoundry-incubator/credhub-api-docs
(charter L77;
the repository
was last pushed to on 2021-08-19, checked 2026-10-10), and docs generated from the credhub code for the
current version. It builds the site with
Middleman 4.4
(build step)
and runs it as a Cloud Foundry app served by the nginx buildpack
(manifest).
Book pages link to both references under docs.cloudfoundry.org/api/uaa/
and docs.cloudfoundry.org/api/credhub/
(book navigation),
and to versioned UAA pages such as api/uaa/version/73.7.0/
(uaa-concepts).
The UAA reference already publishes versions: its build writes each one
under docs/version/<major.minor>.0.
The RFC covers “CF, UAA API” (L13) and asks “Who can we involve to vet this proposal for the UAA API docs and the CredHub API docs?” (L177).
Needs:
Not yet written: whether either API reference must change format to join the pipeline.
The BOSH docs at bosh.io/docs are a separate site built from
docs-bosh with MkDocs and its
Material theme (glossary), not by the book
(mkdocs.yml,
build task).
They are owned by the Foundational Infrastructure working group (FI WG;
charter,
which lists docs-bosh).
The site has 40 tables, all plain Markdown pipe tables (rows written on one
line each, with | between cells), and 302 admonitions (boxed callouts
headed Note, Warning, and so on), counted by this evaluation at docs-bosh
commit 20a4122 (table survey, bosh.io). The RFC
does not mention bosh.io.
Draft position: bosh.io follows the Docs WG’s table and note conventions (R-09 table styles by class, R-07 notes and admonitions). Whether bosh.io moves to a new tool or into the new site is the FI WG’s decision; the Docs WG can advise. See Research areas.
The RFC requires that “The conversion MUST be done by one central migration team to ensure consistency, not by each Working Group individually” (L131). Who staffs it is an open question in the RFC (L174).
Needs:
How the team converts: Migration.
The RFC asks that “Working Group leads and known downstream consumers (e.g.,
SAP BTP, anynines, …; VMware Tanzu works from its own branches and is not
affected) SHOULD be asked whether they consume the CF docs as-is or maintain
their own derivative documentation” (L113). In the non-public pre-review the
Docs WG lead stated that Broadcom’s docs are written fully in-house and do not
rely on the CF doc repositories. The repositories show only the open-source
side: docs-dev-guide removed its commercial branching in July 2026, and its
commit 689faba
says the repository “is now dedicated exclusively to the OSS Cloud Foundry
doc set”. How Broadcom writes its own docs is not visible in them.
The RFC’s open questions still name VMware Tanzu as
a downstream distribution (L168), which does not match L113.
Needs:
Not yet written: what each downstream consumer reuses (raw source or published HTML). That comes from the survey at L113.
People who use Cloud Foundry and read the docs to do so.
Needs: R-18 full-text search, R-16 old URLs keep working (bookmarks and links from other sites), R-02 rich tables, R-06 typed code blocks, R-07 notes and admonitions, R-30 single-page HTML and PDF (to read offline or print the docs as one document).
Search engines, and what the RFC calls “AI-based developer tools” (L22): programs that read the published docs to answer developers’ questions.
Needs: R-20 search-engine and AI-friendly output, R-16 old URLs keep working.