Summary: Large AI models can quickly generate product documentation that looks complete. But whether that content matches real user paths, has been verified, and is safe to publish for external users is still a high-certainty problem. This post records a real documentation engineering practice: how we moved from one-off AI chat generation plus manual patching to a verifiable and reusable documentation production flow built around Rules, Skills, validation Harnesses, and human review. Through this workflow, the documentation team improved the customer-facing quality of complex software docs and moved its focus further upstream, from content writing to documentation platform engineering, knowledge architecture design, and developer experience.

I spent longer than I'd like to admit evaluating static site generators. Hexo, Hugo, Astro, VitePress — I poked at all of them. Docusaurus is what I landed on, and after running it for a while, I don't regret it. It hit the specific combination I needed: write occasionally, keep docs and blog posts under one roof, and not spend a weekend wrestling with CSS just to get a decent theme.

This post is a walkthrough of that entire setup process—every integration, every config file, and a few things that tripped me up along the way. The complete source is on GitHub at heywalter/FlowingDocs. Feel free to fork it, just make sure to swap out the credentials (more on that below).

In my last post, How I Review Technical Docs with AI, I mentioned in passing that before bringing Codex into the workflow, I had already built a small local AI system for catching typos, terminology mistakes, basic awkward sentences, and the occasional formatting glitch.

It was a one-line aside, but a few readers wrote in asking for more. So this post zooms in on that piece: why a local AI content review system is worth building in the first place, how it differs from just calling a hosted LLM, and what it takes to go from a working demo to something a team will actually open every day.

Once your docs fully live in GitHub and follow a Docs-as-Code workflow, review starts to look a lot more like software collaboration. That is mostly a good thing: we get history, branches, pull requests, and a cleaner workflow. But it also means the quality bar rises fast.

Over the past few months, I ended up building a layered review workflow for technical content. I started with a lightweight local validation step for typos and surface-level issues, then added Codex for deeper local and cloud review, and finally used AGENTS.md to turn a lot of tacit review judgment into reusable rules.

This post is not just a tool recap. It is really about why this workflow is worth building, where each layer helps, and where AI review still needs a human in the loop.

As a content creator, my entire job is turning complex information into clear, actionable content. After years of doing this, I’ve developed a serious occupational hazard: I can’t walk past a sign, a screen, or a website without instinctively judging how well (or poorly) the information is designed. It’s basically a reflex at this point.

Recently I ran into three perfect examples that drove the point home. Instead of diving into dry theory, I figured I’d share these everyday “gotchas” so we can all laugh at how easily we get tripped up — and remember to avoid the same mistakes in our own work.

Hello, I'm Walter Gui, a technical writer. Welcome to my blog, Flowing Docs.

Actually, I've wanted to write a blog for a long time, but I kept putting it off. This time, I finally made up my mind to write an article first and set a flag, so I won't give up halfway. For me, writing a blog is about finding a place to organize scattered thoughts and share them. If this content is helpful to you, that would be the best encouragement for me.