cf-docs-rfc-proposal

Audiences

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:

Summary

Each audience, whether it changes the docs, and its main needs:

Who changes the docs

Docs WG lead and approvers

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-group content owners

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:

Occasional contributors

Anyone who opens a pull request to fix a page: a typo, a changed command, an outdated step.

Needs:

UAA and CredHub API doc maintainers

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.

bosh.io maintainers

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.

Central migration team

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.

Downstream consumers

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.

Also affected: people and programs that read the docs

Readers

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 AI-based tools

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.