At Cloudflare I designed a new documentation content type, the cross-product solution guide, and built the authoring system that produces it at a repeatable quality. This case study covers the content model, the information architecture, and the workflow. The companion case study, Cloudflare Cross-Product Solution Guides, covers the published guides as writing samples, and AI-Assisted Content Gap Analysis covers the research that made the case for this content type. The judgment thesis behind the workflow is the subject of my blog post, Where the Script Stops and the Judgment Starts.
The challenge
Cloudflare’s documentation was organized by product. Customers, though, arrive with a goal that crosses several products. There was no content type for goal-first, cross-product guidance, no shared definition of what one should contain, and no scalable way to produce them without each guide becoming a bespoke, writer-dependent effort.
Defining the content type
I defined the solution-guide content type in the public Cloudflare style guide, establishing what a solution guide is, how it differs from a tutorial, how-to, or learning path, and the structural rules that make one: organize by workflow stage rather than product, lead from the reader’s goal, keep the core workflow completable on lower plans, and treat source product documentation as the canonical truth the guide organizes rather than restates.
After launch, I revised the style guide’s content-type selection topic to disambiguate solution guides from the adjacent content types, rewriting the definitions relative to one another so writers know which type to reach for and when.
Public artifacts:
- Solution guide content type definition (Cloudflare style guide) — archived snapshot
- Selecting a content type (Cloudflare style guide)
The content type was defined and merged through the public cloudflare/cloudflare-docs GitHub repository in pull request #29346 — a verifiable record of authorship independent of later edits to the live page.
Information architecture and content model
The content model encodes the decisions that keep guides consistent and maintainable:
- Workflow-stage organization. Each guide is structured by the stages of a customer’s job, with a clear outcome per stage, not by the products involved.
- Goal-first framing. Titles and sections lead from an outcome, with plan tiers surfaced in headings so a scanning reader sees what applies to them.
- Reuse over duplication. Procedures that exist in product docs are rendered through shared partials, so a guide and its source pages stay in sync from one maintained file. Reference data is summarized and linked rather than copied, to prevent staleness.
- Product context in cross-product space. Because any heading can be a reader’s entry point, features carry their product on first mention within each section, so a reader who lands mid-guide is never disoriented.
The authoring system
The guides are produced through a two-command workflow: an audit followed by a draft, with a structured handoff between them. I built the system in three deliberately separated layers using OpenCode, Claude, and Python.
Deterministic layer. Python scripts handle the work that should be identical every run: page discovery, relevance scoring, freshness checks from version history, broken-link detection, configuration extraction, and mechanical structure validation of the draft. Broken-link counts and structural checks are treated as ground truth.
Agentic layer. Claude agents handle judgment-heavy review, but only inside constrained rubrics. A content-auditor agent assesses candidate pages for content health, reuse potential, and goal-first versus product-first framing, citing page evidence for each judgment. A reviewer agent challenges high-relevance assessments for unsupported claims before they move forward. The drafting agent writes from source documentation and flags composed claims with a VERIFY tag for human confirmation. A deterministic check also flags regulatory terms such as FIPS, PCI DSS, and FedRAMP, so no compliance claim ships without a cited source.
Human layer. I designed the decision space the agents operate inside: the rubrics, the goal-first editorial principle, the reuse criteria, and the plan-tier logic. The validation gates reduce risk between steps, but they are not the final authority. Human judgment remains the final gate.
What this demonstrates
- Defining a new public content type and adoption path through the Cloudflare style guide
- Designing a cross-product content model and information architecture from scratch
- Building a docs-as-code authoring system that lets quality scale without a single writer becoming the bottleneck
- Combining deterministic automation and constrained AI agents with human editorial judgment
- Creating enablement artifacts — definitions, patterns, and review standards — that help other writers contribute consistently
Outcomes
Outcomes
The work moved Cloudflare from ad hoc cross-product documentation to a defined solution-guide model with repeatable standards for structure, scope, and authoring.
The content type shipped publicly in the Cloudflare style guide, and the first guides produced from the model became a reference set for future cross-product guidance.
The authoring workflow turned what could have remained a bespoke, writer-dependent process into a reusable system. Deterministic checks handled discovery, freshness, link health, and structure; constrained agents produced auditable assessments and drafts; and human review remained focused on editorial judgment, product accuracy, and launch readiness.