Red Hat Technical Writing Style Guide

Wow, this is a really terrific guide. It's quite long, but it's long because of it's breadth, not because of being overly verbose (IMHO). I particularly appreciate the clear explanations and large number of examples that really help make the concept more concrete. I think this is quite broadly useful even for people that don't work for Red Hat.

Seems useless, as Red Hat does not write documentation

Red Hat has some of the most professional documentation of any distro. E.g https://docs.redhat.com/en/documentation/red_hat_enterprise_...

Looks solid. My gripe with most technical writing (TW) style guides (this one included) is that they mix best practices with conventions:

* "Best practices": Aspects that tangibly improve docs quality. Usually backed up by experimental data or overwhelming consensus.

* "Conventions": Arbitrary decisions that don't clearly improve docs quality one way or the other, except for the fact that they improve consistency, and consistent docs are easier to use.

When everyone in the room has this shared understanding, TW style guide conversations often go much faster and smoother.

I’m not sure I see the upside. Do you have an example you like?

It's a best practice to set commands that are to be typed literally in a different typeface.

It's a convention that most documents use a monospaced courier or monospaced grotesk as that typeface.

Much of it is behind a paywall though. I manage more than a hundred licenced RHEL machines, was an RHCSA and RHCE with a company mail but I'd have to ask someone in my org to give me access. I just blocked access.redhat.com on kagi. F you.

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.

Most of the 'docs' are not behind the paywall, you're mixing up the KCS / FAQ's.

The docs are on https://docs.redhat.com/

I tried to do this back when I was content lead for web.dev: https://web.archive.org/web/20230329155818/https://web.dev/h...

Almost everything in there falls under the "best practices" bucket and there is little discussion of "conventions". If I did it again today, I would try to provide lots more justification and evidence for each guideline.

The upside is that authors focus their limited time/energy on the edits with the highest ROI. E.g. if the author only has time to either A) make the content more scannable or B) use Oxford commas everywhere, I would much prefer that they spend their cycles on A. This doc also reduced friction at review time. When some proposed new content didn't meet my quality bar for whatever reason, I would point the author to specific sections of this doc and ask them to revise their draft based on these guidelines.

During a code review, a request to fix a race condition is much higher priority than a name improvement. I'm arguing that TW style guides need a similar type of distinction.

I can pick out specific examples of best practices versus conventions in the Red Hat guide if it's still not clear.

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.

> paywall

at worst a regwall.

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.

I didn't mix it up but most of the time I stumble upon redhat.com it's KCS (access.redhat.com) articles. Yes it's not "documentation" but if it's worth to create an article because that many people have the same issue I'd say you could add it to your documentation as known issues.

"You need an active subscription" is paywall for me.

Most of this looks quite good!

The only part that throws me for a loop is in the Grammar section, which contains a mix of best practices (like "Prefer active voice to passive voice") mixed with basic rules about subject-verb agreement. The former is what I would expect to see in a Style Guide, while the latter is, I dunno...what I would expect as a basic requirement for passing high school English?

It just feels like for the level of fluency presumably required for a Technical Writer, basic grammar rules should be well understood and not need to be explicitly stated.

Yeah, I was thinking the same.

They got lost in the details.

Especially since AI grammar tools automated B for years now.

I understand having both, particularly in an industry with many non-English native speakers.

I think it would be better to separate the advice as you suggest. Opinionated, or organization-specific, advice in one section and grammar in another.

Ensuring active voice and how to use possessives with product names is style.

"Who vs. Whom" is grammar.

> mixed with basic rules about subject-verb agreement (...) [that] I would expect as a basic requirement for passing high school English

I reckon this is just a poorly picked example on your end, because the guide explicitly states the following about that:

> There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here.

Regardless, sometimes (oftentimes?) technical documents are written by people who are not actually technical writers. A good number of those will also have a native language other than English. And in a lot of high schools, passing the English class is really not a very high bar, especially when failing people en masse is not really an option. You can only coerce people to learn a language so well.

Yes agreed, and they also extensively write and maintain man pages distributed with common FOSS software, and they are some of the best man pages I've ever seen. They are also freely contributed to the upstream projects so that the entire Linux ecosystem benefits.

I do wish the knowledge base wasn't behind a log in, and Red Hat isn't perfect (there are plenty of things that either don't get updated for new RHEL releases and end up cut, or aren't comprehensive enough), but they do contribute a ton to documentation that benefits everybody.

You manage over a hundred licensed RHEL machines but don't have an active subscription to access.redhat.com? Somebody is doing something terribly wrong in your org. How do you open support cases without that, or even manage the subs?

For the record I think Red Hat shouldn't put those behind a login, but that's a different argument

I would even be okay with maybe including some "common" mistakes in the style guide if they are particularly prone in your field/organization--those are useful for even native speakers sometimes that confuse there/their/they're, etc. [0]

My qualm is that a "Style Guide" is about explaining "There are multiple ways to do this correctly, but this is what WE prefer." For example, "Prefer American spellings of color/favorite over British colour/favourite, etc."

But with basic subject-verb agreement, it's a requirement of the language and not really up for debate. If your subject doesn't agree with the verb in number and gender, IT ARE WRONG.

[0] https://www.oxfordinternationalenglish.com/common-english-gr...

Section 4.6 is certainly ridiculous, but I suppose you can just ignore it.

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.

Yep. About half of the content in my workplace's style guide wouldn't need to be in it if those rules weren't repeatedly broken by borderline-illiterate software engineers who are brilliant with code, probably, but write in fragments, end sentences in commas, and pluralize words with 's. Getting consistent SVA in their writing might as well be two pay grades above them.

I could ask for access I assume it's just a mail but I don't want to bother them because I can find a solution one or two results down from the redhat site anyway. I've worked with Linux and without a support contract for long enough that I know how debug and fix things. I wouldn't get direct access to support cases anyway. Our Linux guys provide a bash script to auto enroll.

It's not a login. It's a login with an active subscription. Are those article that valuable that they can't provide it for everyone with a @company.com address that has >n licences?

Active voice isn't always best for technical writing. When describing a procedure it can lead to a stilted sequence of imperatives rather than a more natural reading with some passives mixed in. What they teach in school for general English writing style doesn't have universal applicability.

Fair, I forgot they changed it to require an active sub rather than just an account. That was a bad move IMHO. And yes I fully agree they should at a minimun automatically allow access to everyone with @company.com with >n licenses.

Pure speculation, but I'm guessing they view the knowledge base as part of "support" (or like level 1 or something), which is why they're so restrictive. I think they greatly underestimate the number of people like us though that already use RHEL but don't want to bother with accounts because we can get by without it, but would benefit from having the access. They don't seem to understand the friction their policies create, and I think that's deeply unfortunate.

> But with basic subject-verb agreement, it's a requirement of the language and not really up for debate. If your subject doesn't agree with the verb in number and gender, IT ARE WRONG.

I’m very confused about what you are talking about, when

> > There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here.

per this comment:

https://news.ycombinator.com/item?id=44524290

As you mention what is or isn’t up for debate, why do you keep bringing up to debate something that is explicitly referenced but not discussed or addressed by TFA? The author already beat you to the punch by opting not to debate that point, and that’s the one you specifically want to talk about?

Are you fishing for red herring? Color me confused lol

> Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test",

This one seems a little much. I've used this term in work writing within the past week (not in official documentation, but I do also write official documentation). I tried to look up what the acceptable alternatives are (since Section 4.6 doesn't specify one for that rule), but it seems most possible alternatives already have other, distinct meanings: https://english.stackexchange.com/questions/282282/near-univ...

From that section, I really like:

>"Avoid superlatives in job titles and descriptions, especially problematic terms such as "guru", "ninja", "rockstar", or "evangelist"."

At a past job, it was actually embarrassing to introduce some of my colleagues in meetings as shit like "Data Guru" and "Marketing Guru".

(I'm sure we can skip the 100,000th argument about the rest of the section).

I don't need to fish, the subject-verb agreement was an example. Grammar points 2.2.1 (Pronoun-antecedent agreement, which they did feel the need to go into in detail) and 2.5 (Using Who, Whom, That, and Which Correctly) are other things I would consider "not up for debate".

Might be just my ESL self being silly but these examples both read horribly:

> For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than

Even without reading the next bit I just knew that no, this does not read better. The insertion of "a site for reference material and other resources" just makes this sentence horrible to follow period.

> "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence.

This reads silly for another reason: websites don't... introduce things. Website owners might. Also, I feel it should say "reference materials" not "reference material".

It might be dialectical, but in American English, I think “reference material” sounds fine. (Maybe “material” in this context is uncountable or collective or something)

you can grab a free dev sub and it unlocks the KB and quick fixes too. Unless that changed relatively recently.

I usually use "smoke check/test" or "smell test", but if you have a specific context in mind, maybe I can give you a different alternative phrase I use or two.

Definitely not something I'd force onto others either though.

(I’m a red hatter) anyone can get the Red Hat Developer subscription for free and get full access to the knowledge base.

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_...

Thank you for the clarification! That's what I thought, but then I found a bunch of comments indicating they had changed it. Glad to hear it's still free

I agree, I just don’t know why you would pick that as an example, since it is the example the author picked for something that wouldn’t be up for debate, then you yourself go on to debate it. It seems explicitly in bad faith?

Thanks. Maybe I'll do it the next time. That seems like less friction than having to write our representative / admim however you call the people that could add me to our subscription. But why do you put it behind that if it's free anyway?

Are there any comparisons between this and other style guides from the likes of IBM, DEC, Sun, Apple (Early MacOS), Microsoft, etc?

All of these had in-house printshops, so would have had some style guides even if just to provide consistency for internal use.

Parts of this are excellent. I teach a contract-drafting course for 2L and 3L law students. Some aren't good writers. When I mark up their work, I can provide them with links to specific points in the RH guide.

Some parts aren't so great. Example:

> EXAMPLE[:] Remote users can connect to network resources simply by authenticating to their local machine. IMPROVEMENT[:] Remote users can connect to network resources by authenticating to their local machine.

It's not at all obvious that you improve the sentence by omitting "simply" — you're losing a bit of information that might be significant, to some readers and certainly to the writer.

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!

In my experience, technical people tend to tag way too many topics with “simply”. It is usually best to get rid of the word.

[delayed]