[HN Gopher] Red Hat Technical Writing Style Guide
___________________________________________________________________
Red Hat Technical Writing Style Guide
Author : jumpocelot
Score : 132 points
Date : 2025-07-10 15:01 UTC (7 hours ago)
(HTM) web link (stylepedia.net)
(TXT) w3m dump (stylepedia.net)
| freedomben wrote:
| 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.
| ban2ly wrote:
| Seems useless, as Red Hat does not write documentation
| curt15 wrote:
| Red Hat has some of the most professional documentation of any
| distro. E.g
| https://docs.redhat.com/en/documentation/red_hat_enterprise_...
| bauruine wrote:
| 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.
| worthless-trash wrote:
| 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/
| bauruine wrote:
| 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.
| SSLy wrote:
| > paywall
|
| at worst a regwall.
| bauruine wrote:
| "You need an active subscription" is paywall for me.
| freedomben wrote:
| 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
| bauruine wrote:
| 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?
| freedomben wrote:
| 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.
| jwildeboer wrote:
| (I'm a red hatter) anyone can get the Red Hat Developer
| subscription for free and get full access to the
| knowledge base.
| freedomben wrote:
| 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
| bauruine wrote:
| 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?
| SSLy wrote:
| you can grab a free dev sub and it unlocks the KB and
| quick fixes too. Unless that changed relatively recently.
| freedomben wrote:
| 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.
| kaycebasques wrote:
| 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.
| lelandfe wrote:
| I'm not sure I see the upside. Do you have an example you like?
| dsr_ wrote:
| 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.
| kaycebasques wrote:
| 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.
| k__ wrote:
| Especially since AI grammar tools automated B for years
| now.
| david422 wrote:
| 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.
| kaycebasques wrote:
| 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.
| golergka wrote:
| 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.
| smarx007 wrote:
| 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
| ndespres wrote:
| 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.
| kaycebasques wrote:
| This doesn't create slop. It's just an automated editor. A
| linter for natural language.
| smarx007 wrote:
| 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_...
| golergka wrote:
| 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.
| layer8 wrote:
| 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.
| irskep wrote:
| 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.
| AdmiralAsshat wrote:
| 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.
| k__ wrote:
| Yeah, I was thinking the same.
|
| They got lost in the details.
| unethical_ban wrote:
| 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.
| AdmiralAsshat wrote:
| 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...
| aspenmayer wrote:
| > 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
| AdmiralAsshat wrote:
| 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".
| aspenmayer wrote:
| 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?
| perching_aix wrote:
| > 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.
| starkparker wrote:
| 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.
| kevin_thibedeau wrote:
| 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.
| dmurray wrote:
| I expect even quite literate native English speakers to
| sometimes make mistakes with subject-verb agreement in any form
| of sentence other than the most trivial.
|
| E.g. I am not surprised to read "Distance to the server is one
| of the factors that affects latency."
| GLdRH wrote:
| Section 4.6 is certainly ridiculous, but I suppose you can just
| ignore it.
| jacobgkau wrote:
| > 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...
| perching_aix wrote:
| 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.
| wmeredith wrote:
| Are we just disregarding the differently-abled people who
| have a diminished sense of smell? /s
| duskwuff wrote:
| It's not a hypothetical situation; I know people with chronic
| mental health conditions who find this usage of the word
| "sane" specifically hurtful. It's avoidable; use "reasonable"
| as an adjective and a phrase like "consistency check" as a
| verb, or a more specific term like "bounds check" if
| applicable.
| qualeed wrote:
| 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).
| perching_aix wrote:
| 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".
| BalinKing wrote:
| 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)
| Chilko wrote:
| That sentence structure of the first example ('subject, long
| tangent, conclusion') is very common in the German language
| (and a major annoyance for me when reading German), so perhaps
| the author has that background?
| markedathome wrote:
| 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.
| dctoedt wrote:
| 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 lose some compressed information: in this case, an
| implication that alternatives to local authentication might be
| more complex. This implication might be significant, to some
| readers and certainly to the writer.
| Scubabear68 wrote:
| In my experience, technical people tend to tag way too many
| topics with "simply". It is usually best to get rid of the
| word.
| dctoedt wrote:
| Fair.
| IshKebab wrote:
| I agree. It usually seems simple to the author but it's
| bloody annoying when some documentations _says_ something is
| simple and it actually isn 't.
| dctoedt wrote:
| Fair. Context matters.
___________________________________________________________________
(page generated 2025-07-10 23:00 UTC)