We rebuilt docs.cloudzero.com from the ground up. The result is a documentation site organized around what you’re trying to accomplish rather than feature names and jargon.
Why this matters
CloudZero is growing fast, and the documentation needs to keep pace with what our customers are doing with the platform. The goal was to make finding answers faster, match the structure to how you actually work, and keep everything current as new features ship. The docs are also structured for the new age of AI agents and assistants that rely on documentation to answer questions accurately. Whether you’re setting up your first connection, fine-tuning cost allocations, or asking CloudZero’s AI Hub a question, the docs should get you there without getting in the way.
What we built
We restructured and rewrote the entire site. Navigation is consistent across sections, breadcrumbs keep you oriented, and the new Changelog in the top nav replaces the old What’s New page so you always know where to find what’s changed. We verified every existing redirect as part of the deployment, so nothing you’ve bookmarked breaks.
We audited 108 pages, grew the glossary from 23 to 47 verified terms, and consolidated concepts like cost organization with CostFormation from 31 separate pages down to 13 with no content lost. The existing docs served their purpose, but as CloudZero grew, we needed them to be better. AI was good at surfacing what needed attention and making recommendations based on industry best practices in documentation writing; humans were good at deciding what to do about it.
We also wrote the new docs with AI consumption in mind. CloudZero’s AI Hub and MCP integrations parse the documentation to answer customer questions, so every page had to be structured in a way that an LLM could interpret accurately without hallucinating. In practice, that meant doing the same things that make docs good for humans, like clear headings, consistent terminology, no contradictions, and critical information in text rather than only in screenshots. Well-written documentation for people and well-structured documentation for AI is basically the same thing.
How we built it
The rules were clear from day one. The AI was the documentation writer, not the subject matter expert. It wasn’t allowed to state any product fact it couldn’t trace to source material. I read every page multiple times, catching nuances and edge cases that AI occasionally missed. On more than one occasion, AI produced content that was technically plausible but factually wrong, with confidently stated claims that didn’t match the actual product. Because the process required human verification of every fact, none of it reached customers, and the rules were tuned to reduce those mistakes going forward without overfitting them.
Side anecdote: before I started getting human reviewers, I thought about whether someone might just use AI to rubber-stamp the review. If this started happening, I had a plan ready, kind of like Van Halen’s brown M&M test. Something like slipping in a recommendation to place a seagull on a ColecoVision server to resolve a billing discrepancy. Unsurprised by my thorough colleagues, I never got to have the fun. Every reviewer engaged with the content, pushed back on details, and genuinely wanted this to be right.
One lesson I took away was recognizing when I started talking to AI like another human. The longer you work with it, the easier it is to forget you’re not talking to a human. You’re talking to zillions of switches (some may say it’s all going through a series of tubes). The moment I started anthropomorphizing it, expecting it to learn from corrections like I was talking to a person instead of mechanically fixing my inputs, the results fell apart. Every time I traced a bad output back to its cause, it came down to my process, whether it was an ambiguous instruction, a session that ran too long, or a rule I forgot to reload. The AI is a mirror of the process you give it.
One thing that became increasingly important was keeping an eye on the cost of my prompts. It kept me honest about being to the point, giving the AI the inputs it needed, and choosing the right models for the job. After all, documentation writing often needs large context windows to avoid hallucinations and keep things consistent, and doing it cleanly and efficiently is important to keep costs under control. CloudZero helped here. We connected our Anthropic usage just like any other SaaS or cloud provider, and AI Signals gave us the actual cost of prompts in real time. So while the AI was rewriting docs, we had real-time visibility into what the Claude usage was costing us. It’s the same visibility any CloudZero customer gets when they connect their AI platforms.
AI is at its best when a human owns the outcome. It made it possible for a small team to restructure 108 pages in a few months. The human is what made the difference between documentation that sounds right and documentation that is right. Without that, you’re just burning through tokens hoping it eventually gives you what you asked for. And because the style guide, the rules, and the process are all in place, updating a page now is fast. Our customers get accurate, up-to-date documentation as fast as we can ship the features behind them.
Take a look
The new site is live at docs.cloudzero.com. If you want to see the previous version, open the version dropdown in the top-left and select Classic.
