cf-docs-rfc-proposal

Cloud Foundry Documentation Modernization — RFC Proposal

Findings, proofs of concept, and working drafts for modernizing the Cloud Foundry documentation stack.

This repository is published with GitHub Pages. Read it at https://norman-abramovitz.github.io/cf-docs-rfc-proposal/, where links between documents, screenshots and code samples render as a site. The same files also read as written here on GitHub.

Background

The CF docs at docs.cloudfoundry.org are built by Bookbinder, a Ruby command-line tool (Bookbinder), from docs-book-cloudfoundry, which collates the docs-* content repositories (*.html.md.erb sources) into one site. Each repository maps to a fixed URL directory (config.yml), so a page’s URL identifies the repository and file to edit.

cloudfoundry/community#1642 proposes moving this content to Markdown on a modern static site generator, hosted on GitHub Pages. This repository holds the evidence gathered to inform that proposal.

The RFC text is not the pull request’s description; it is the one file the pull request adds. Read it at:

Start here

Looking for one document? The cf-docs index lists everything published here.

There are three draft documents, and each can be read on its own. They cover what is known as of 2026-10-10 and mark what is not yet written.

  1. Requirements: the Docs WG’s draft position on what it is looking for in a new documentation stack. Each requirement has an ID and a short phrase that says what it is about, such as “R-03 column widths as hints”; the other documents cite them that way.
  2. Tooling: the tools evaluated, the input formats they read, how today’s pages convert into them, and the extensions each needs. It is neutral evidence and makes no choice.
  3. Proof-of-concept results: what each tool built from real Cloud Foundry pages, next to the page as published today. It is also neutral evidence.

Only interested in the results? Go straight to the side-by-side pages. Two outputs side by side puts any two versions of a test table next to each other, the published page or a tool in one of its modes, with the text an author writes for each below. The comparison page shows the published table next to all four tools at once. Tables, page by page writes each test page out with its inputs and the differences found.

The glossary explains the terms further. Each document defines its terms where it first uses them, so the glossary is optional.

Contents