Status: draft Docs WG position, incomplete — covers what is known as of 2026-10-10.
Questions the requirements depend on that nobody has answered yet. For each:
why it matters, what is known, and what would answer it. Requirement IDs
refer to the requirement list. 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).
Scope
Which repositories feed the docs, and who owns each?
Why it matters: every area needs an owner before it migrates
(R-17 an owner for every area), and the URL mapping
depends on the repository list (R-15 URL identifies the source).
Known: the book’s
config.yml
(the settings file that tells Bookbinder, today’s build tool, which
repositories to collect) lists 12 sections, each a docs-* repository
mapped to a URL directory, plus sample-code repositories with no pages. A
survey of tables covered the 15 docs-* repositories that are not
archived (this evaluation’s table survey, 2026-10-09). The book’s own CODEOWNERS file
(which names who must review changes) lists one team for everything,
@cloudfoundry/wg-app-runtime-platform-docs-approvers.
What answers it: the inventory in the RFC’s first phase (L112,
L167).
Is bosh.io in scope?
Why it matters: the RFC does not mention it, yet it is Cloud Foundry
documentation with its own tables and notes (R-07 notes
and admonitions, R-09 table styles by class), and the
book already sends all of /bosh/ to
bosh.io/docs (R-16 old URLs keep working).
Known:bosh.io/docs is built from
docs-bosh with MkDocs and its
Material theme (glossary;
mkdocs.yml,
build task), and is owned by
the Foundational Infrastructure working group (FI WG;
glossary; its
charter lists docs-bosh).
Its 40 tables are all plain Markdown pipe tables; it has 302 admonitions
(boxed callouts headed Note, Warning, and so on); both counted by this
evaluation at docs-bosh commit 20a4122
(table survey, bosh.io). The rest of bosh.io (release and stemcell pages) loads
the stylesheet and scripts that the docs build produces
(bosh-io-webmain.go,
layout stylesheets
and script), so changing the docs tool
affects the whole site.
What answers it: the FI WG, with the RFC authors. Draft position:
bosh.io follows the Docs WG table and note conventions; a tool or hosting
change is the FI WG’s decision.
How do the UAA and CredHub API references fit?
Why it matters:R-29 API docs in the same pipeline.
Known: the UAA API reference is built with Slate (a generator for
one-page API references; glossary) from examples
that Spring REST Docs writes during the API tests
(glossary;
UAA Gradle build). CredHub also
uses Spring REST Docs
(CredHub Gradle build).
Book pages link to both under docs.cloudfoundry.org/api/
(book navigation),
and to versioned UAA pages
(uaa-concepts). The RFC asks who can vet the proposal for them
(L177).
What answers it: the UAA and CredHub maintainers: where each reference
is built and published, and whether it must change format to join the
pipeline.
What do downstream consumers reuse?
Why it matters: if anyone copies raw source, the source format and
partials matter to them (R-05 partials and reuse); if
they link to the site, URLs do (R-16 old URLs keep working).
Known: the RFC names SAP BTP and anynines as examples and says VMware
Tanzu “works from its own branches and is not affected” (L113), but its
open questions still name Tanzu (L168). In the RFC’s pre-review (comments
on an earlier draft, in a document that is not public; a
pull request comment records it) the Docs WG lead stated that Broadcom’s docs are
written fully in-house (see commits
docs-book-cloudfoundry bdb9de7
and
docs-dev-guide 689faba).
What answers it: the consumer survey in the RFC’s first phase (L113).
Content
Are partial names in variables still needed?
Why it matters:R-05 partials and reuse. A partial is a file of content
included in other pages. Here the partial’s name comes from a variable (a
named value defined once and inserted at build time), so the include is
decided at build time. No tool has been tested with that yet.
Known: the book’s template_variables.yml maps
scale_table: "oss_scale_table"
and roles_table: "_oss_roles_table".
The oss_ prefix suggests that another edition of the docs once swapped
in its own table; that is an inference, not documented anywhere found.
Every tool in the tables round (the first concept, worked by hand in four
candidate tools; results)
included the scale-table partial when it was
named directly
(sources).
What answers it: the downstream survey above, and a search of the
content repositories for partials included through a variable.
Found by the partials round (2026-10-11): 10 variables name a
partial, and no page at the surveyed commits uses any of them; every
call names its partial directly. The form served an open-source and a
commercial edition, and the commercial branches were removed in July
The round recommends resolving such names at conversion, for
review (partials results).
Decided (Docs WG lead, 2026-10-11): not needed. The converter
resolves any such name, and the 10 variables are removed in the
cleanup before conversion (R-24 markup cleanup
before conversion).
What should undefined variables show?
Why it matters:R-04 variables everywhere asks that an undefined
variable be reported, not shown as empty text.
Known:metadata_ref (in metadata) and bosh_cli_link (three times
in troubleshooting_slow_requests) are defined nowhere in the book; the
published pages show nothing in their place
(sources). Other pages may have
more.
Found by the variables round (2026-10-11): 28 names used on pages
are defined nowhere (38 uses), and 31 defined names that pages use are
empty (44 uses). All 82 render as nothing today. Each tool can be made
to report an undefined name, in different ways
(variables results).
What answers it: a scan of every page for variables missing from
template_variables.yml, then the page owners say what each should be.
Which table styles beyond the standard one?
Why it matters:R-09 table styles by class. A style class is a name the
site’s stylesheet gives a look to (glossary).
Known: a survey of all 238 tables in the docs and tutorial repositories
found one class in use, table (this evaluation’s
table survey, 2026-10-09). The closest thing to a second style is a
compact one for comparison grids and long reference tables. The tables
round added table-media, an image grid, as an example of how a style is
added (template conventions).
What answers it: the Docs WG choosing from the survey’s
table families.
What do the concepts not yet worked require?
Why it matters: these requirements are stated from the tables round
and from reading the source:
Each concept (one documentation feature, worked through every candidate
tool) can change them.
Known: tables are done. Headings are converted in all four
hands-on tools, with their conventions under review
(headings results). Notes
and admonitions are converted in all four as well, with the map from the
book’s kinds to each tool’s types still open
(notes results). Variables and
partials are converted in all four, with their conventions under review
(variables results,
partials results). Copyright and
build-time values are built in all four, with the year rule open
(build-time values results).
Cross-repository links are converted in all four, with every link
reaching its page and anchor when pages keep the book’s .html URLs
(cross-repository links results).
Code blocks are converted in all four; every block keeps its text, type
and copy button once written as the tool’s own code block
(code blocks results). The tables round already
found problems outside tables: heading anchors written as <a id>, terminal
blocks, the * lost in Accept: */*, and HTML-valued variables
(open questions).
What answers it: the review of each round’s conventions. Every
concept in the list now has a round.
Should the copyright year follow content changes?
Why it matters:R-25 build-time values are expected differences.
Known: the footer prints the build year
(<%= Time.now.year %>), so
the year changes on every build. A conversion that only changes the format
may not warrant a new year.
Found by the build-time values round (2026-10-11): five answers,
from the build’s year to no year, with what was observed for each.
Every year rule gives 2026 site-wide this year. A content year needs a
list of commits that do not count as content, and the conversion
commit would be one of them
(build-time values results).
What answers it: a Docs WG decision, with the Cloud Foundry
Foundation if it holds a view on copyright notices.
Decided (Docs WG lead, 2026-10-11): the newest content year on
the site, from the same helper that sets page dates; a fixed first
year if the Foundation prefers it. Holder: “CloudFoundry.org
Foundation, Inc.”, as in the repositories’ NOTICE files, to be
confirmed with the Foundation.
Site and services
Does “open source only” cover services?
Why it matters:R-19 open source only, R-18 full-text search.
Known: every tool evaluated so far is open source (licenses in
Tools). Algolia DocSearch (a hosted search
service, free for public technical documentation per Algolia’s
own page;
glossary) and GitHub Pages (GitHub’s
hosting for static sites; glossary) are
services that are not. DocSearch’s search client is
MIT-licensed,
but it needs an Algolia application ID and API key
(code).
The RFC names self-hosted search options such as
Pagefind, which builds its index from the built
site (options)
(L170).
What answers it: a Docs WG decision.
What does search do today?
Why it matters:R-18 full-text search. The RFC says “Search is broken
or disabled” (L21).
Known: the book’s own files do not provide search. None of its
layouts mentions it, and its
search.html.erb holds only a title and an
escaped <%%= yield %>, which prints as text (both at commit 30dfa57).
What answers it: a check of docs.cloudfoundry.org today.
Known: the RFC starts with one version, v1.0, and leaves the model to
a later Version 2 (L92, L94). In the non-public pre-review the Docs
WG lead noted that there is one current version of Cloud Foundry and of its
docs, with history kept in GitHub. The book builds each of its 12 sections
from one branch, master (config.yml). The UAA API reference already publishes versioned
pages (build).
What answers it: experience with Version 1, as the RFC proposes.
Should the site publish an llms.txt file?
Why it matters:R-20 search-engine and AI-friendly output.
llms.txt is a plain-text index of a site’s pages
for AI-based tools.
Known: the RFC lists it as optional (L41) and as an open question
(L173).
What answers it: a Docs WG decision once the tool is chosen.
Who controls hosting and the domain today?
Why it matters:R-16 old URLs keep working depends on whoever can
change DNS at cutover (the moment the new site replaces today’s site at
docs.cloudfoundry.org); R-27 a named owner for every task.
Known: the RFC says the current hosting is “managed outside the
community GitHub organization” (L24) and asks who owns the domain
(L178).
What answers it: the Cloud Foundry Foundation and the current hosting
owner.
Known: the book’s redirects.rb has 85 rules: 40 lead to a page, 30
to a page that no longer exists, 3 to another redirect, 12 off the site,
and one can never match, because browsers do not send the # part of a
URL to the server. On a static host each tool writes a redirect as an
HTML page
(cross-repository links results;
survey).
What answers it: each area’s owner, with the Docs WG.
Governance
Who maintains shared extensions, and how does a working group ask for one?
Why it matters:R-13 no per-WG extensions. An extension is code added
to the build tool so it handles markup it lacks
(glossary).
Known: in the tables round, Docusaurus, Zensical and Starlight each
needed one small extension for column roles and “don’t wrap”
(list-table.js,
list_table.py,
list-table.mjs).
Antora needed none for the hints; its 8-line script, which puts wide
tables in a scrolling box, is page layout, not a hint extension
(results). The RFC’s wording at
L100 and L104 does not allow for this yet.
What answers it: a Docs WG decision on ownership and a request
process, and the RFC authors’ response to the suggested wording.
Who staffs the central migration team?
Why it matters:R-23 one central conversion, R-27 a named owner for
every task.