5 posts tagged with "Technical Writing"

Reviewing technical documentation is often a frustrating trade-off. Manual proofreading is slow and tedious, but feeding documentation to generic AI or cloud LLMs quickly turns into an engineering headache. Generic grammar checkers don't understand code syntax—they happily translate inline API parameters, rewrite code comments, or rename terms like principal to principle in your IAM guides. On top of that, unreleased features and internal architecture docs often cannot be sent to third-party cloud APIs due to privacy and compliance boundaries.

Over the past year, I built and ran a local-first, small-model review pipeline across an internal repository of roughly 380,000 characters of technical docs—designed specifically to protect code fences, respect custom terminology, and run entirely offline.

Following my earlier architecture post, a few folks asked if the code would be available. It originally started as a rough internal script that was "just good enough for us," so I spent the past few months cleaning it up, decoupling it from our private setup, and adding tests. Today, DocSifter is open source under the MIT license, and I hope it serves as a helpful reference for teams tackling similar challenges.

DocSifter is now open source under the MIT license.

For a quick look at the complete workflow, open the interactive product story.

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.

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.

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.