Red Hat Technical Writing Style Guide

This seems like one of the perfect use cases for AI. Have the AI ingest the style guide, and then comment on your written work to point out where your work does not adhere to the style guide.

Lots of people have tried it. The problem is the sheer number of rules in a typical technical writing style guide. I continue to believe that a fine-tuned model is the way to go, and I made a lot of progress on that front, but I learned firsthand how labor-intensive feature engineering can be.

The most reliable non-fine-tuned method I have seen is to do many, many passes over the doc, instructing the LLM to focus on only one rule during each pass.

There’s so much value in consistent, expertly-written technical documentation that outsourcing it to the hallucination machine is a pointless exercise in aggravation. I do not wish to read machine-mangled slop. I want an expert to write expertly.

This doesn't create slop. It's just an automated editor. A linter for natural language.

Would you pay (a very small amount) for it? As another commenter absolutely correctly pointed out, just putting this guide and your diff into ChatGPT would yells bad results, but looks like something absolutely doable with a proper multi agent system and time invested in tuning it. (This kind of configuration is also how you get good results from cheaper mini models btw). I’m looking for a small indie project right now, and this seems like a great fit.

One agent and some hard code to extract doc diffs with relevant code, parallel agents for different rule groups, tool agent to look up existing patterns and related material in the codebase, consolidator agent to merge the comments and suggestions, that’s how I would do it, for the first version at least. All of them fine tuned, ideally.

They will inevitably mix it up with other style guides they trained on. As a sibling says, fine-tuning would work better, but the training material for that may take some effort to create or validate.

I am afraid the choice in many OSS projects is not slop vs expert-written content but LLM-assisted content or nothing.

I recently produced a bunch of migration guides for our project by pointing Claude 4 Sonnet at my poorly structured Obsidian notes (some more than 5 years old), a few commits where I migrated the reference implementation, and a reasonably well-maintained yet not immediately actionable CHANGELOG. I think the result is far from top-notch but, at the same time, it is way better IMO than nothing (nothing being the only viable alternative given my priorities): https://oslc.github.io/developing-oslc-applications/eclipse_...

I had moderate success using https://www.iso.org/ISO-house-style.html converted to markdown and narrowed to the guidelines starting with "Plain English" and ending before "Conformity and conformity-related terms" (plus a few other rules up to and including "Dates"). A quick estimate puts the whole Markdown document at 9869 tokens - quite manageable. I generally prefer the style of the Microsoft Writing Style Guide but ISO house style is the only one that fits nicely into a prompt.

Looking forward to your model/product!

P.S. https://www.gov.uk/guidance/style-guide/technical-content-a-... also looks useful

I threw together a vibecoded tool to do this, as a personal experiment. It splits the guide into several runs, each focusing on a different style guide section. Here's the diff it gave for the Claude-authored README for the tool, which I called 'edit4style': https://gist.github.com/stevelandeydescript/14a75df1e02b5379...

And here are its style comments: https://gist.github.com/stevelandeydescript/a586e312c400769b...

I don't plan to release the code, since I don't really want my docs to be written in this voice. But it doesn't feel entirely unhelpful, as long as I'm personally curating the changes.