I think good technical writing is a lot like good interior design.
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
Maybe that's a good recipe for reliable technical documents, but arguably not great ones. Some of my favourites writers - Donald Knuth, Leo Brodie, Marshall Kirk McKusick, Harley Hahn, Jeff Duntemann, Beej, Nils Holm, surely missing more - write with a lot of flair and personality. I mean, it certainly doesn't feel cold and lacking in emotion. Oh, Dennis Yurichev too.
A friend who ran a mildly popular dev tool (4k+ stars) kept really stellar docs, and his process of updating them was to sit down with a bottle of whiskey every few months, and doing a marathon doc-writing session. the brand voice would come from him being a funny human and getting a little tipsy.
I suspect his silly and fun-sounding "kinda drunk" brand voice was what set them apart from all the other boring dev tools in the space.
This is true, but the general advice one gives through, for example, publishing a style guide, should focus on producing reliable outcomes over great outcomes. I'd happily lose most of the great documentation I've read in the course of my work (not that much) for never having to read inaccurate or woefully incomplete documentation ever again.
Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, and optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims.
bleeding edge
Do not use.
boil the ocean
Do not use. State exactly what you mean, such as "increase the scope hugely".
Funny thing is that to people who use those terms regularly, they are "stating exactly what they mean".
I.e. "increase the scope hugely", the word "scope" itself comes from greek with its core meaning revolving around "viewing" or "looking". It's only because we are all familiar with it also meaning the scale / amount of things a project should cover, that we all understand. (I guess there's a metaphor of the project "looking over" more as the number / magnitude of goals increases.)
So it shouldn't be "state exactly what you mean", because they are.
It should be more like: "state what you mean using widely used language if possible"
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’ve been on both sides of this, and I’ve come to the realization that it depends on the audience of the writing. It seems like this is for Red Hat authors writing miscellaneous docs for a range of users. Consistency is important there, so that Red Hat seem consistent in their messaging, as a single user could be reading material from many authors. It would look sloppy if the small stuff is all over the place.
Many times, a user receives communication from a single writer. This could be a consulting arrangement, or a small company, or any number of cases really. Those users are probably going to be consistent with themselves anyway, so there’s less need to be as specific on the small stuff. In that case a guide is really just trying to knock off the obvious rough edges in someone’s writing to make sure they’re actually communicating the information.
Using a monospaced typeface for that purpose isn't only convention; it reflects the fact that when those commands are typed literally, it will be in a terminal which almost certainly itself uses a monospaced typeface. I think I'd say that setting literal command text in a monospaced face is a best practice.
[EDITED to add:] I agree with the general point about distinguishing best practices from conventions, though. (But there are also intermediate possibilities. "Best practice for us because it fits with conventions we've become used to". "Best practice for us because of some peculiarity of us or our work, even though for other groups it might not be so good".)
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.
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.
> 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.
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.
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.
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."
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.
> 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.
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
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".
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?
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)
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?
>This reads silly for another reason: websites don't... introduce things.
The way they're using "introduces" does feel awkward, but in general, it's fine to say that a website "introduces" something.
For example, the Homestar Runner website introduced the world to Strong Bad. Or Action Comics #1 introduced Superman. You wouldn't really say that the author of Action Comics #1 introduced Superman.
Going 100% by vibes regarding this, but I feel "introduced the world to" / "introduced x to the world" being a very established phrase is what makes it overpower the awkwardness that's otherwise present.
For example, "Or Action Comics #1 introduced Superman." immediately feels more awkward, the reason it's not quite as awkward as RedHat's example is because it's in-context and doesn't explicitly mention "website", so one could conceivably mistake it for a magazine instead (which I take it probably was/is, an online one specifically).
Using "website" like this is like suggesting they're a publication or a periodical of some sort, which is true for some, but not in general (e.g. news sites?), making it weird.
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.
Pretty solid - I'll add this to my list that I refer to for writing. I often use the Australian Style Manual [0] and Divio Documentation System [1] as a foundation to technical writing and also user documentation.
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.
> 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...
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.
Then those people are unreasonable, and need to adjust their outlook. It is neither healthy for them, nor fair to others, to take such great offense at harmless words.
But words evolve, and we do actually change which words we use. We've been doing it since... forever. And, somehow, people still manage to act surprised when it happens. As if it's their first day on Earth.
There's a lot of terminology around just mental illness that we have decided to leave in the past. And, a lot of it is for good.
One benefit of changing our language is we get a second chance. We can be more specific, more fine-grained, or more accurate. For example, sanity check is vague. If it's a bound check, we might say bounds check. That's more accurate. If it's a consistency check, we might say consistency check.
We want our language, particularly in technical pieces, to be both inclusive and precise. What I mean is, we want it to include every thing it should, and nothing it shouldn't.
For example, in Medical literature you'll often see the term "pregnant person" or "pregnant people", or even "people who may be pregnant". At first glance, it seems stupid. Why not just say "women"? Women is imprecise. There's a variety of people who would not identify as a woman who may be pregnant. If they get, say, a form with that verbiage they might mark "no, I'm not a woman". But they SHOULD mark "yes, I am a pregnant person" or "yes, I am a person who may be pregnant". It doesn't even just include transgender individuals - it also includes people born intersex, or people born without a uterus who do identify as a woman. There's women who may be pregnant and women who may never be pregnant, just as there are people who do not identify as women who may be pregnant. The word "woman" is then imprecise, confusing, and includes people it shouldn't, as well as excluding people it should.
The point is as stated - "women" does not mean the same thing as "pregnant person" or "person who may be pregnant", which are both more precise terms. Both forwards and backwards.
Meaning yes, not every woman can get pregnant, but also not every pregnant person may identify as a woman. Suppose an intersex person born with a uterus who is pregnant but has lived their entire life as a man.
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.
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.
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.
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 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...
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.
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.
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.
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_...
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.
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.
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.
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 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?
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.
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?
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 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.
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
I suspect his silly and fun-sounding "kinda drunk" brand voice was what set them apart from all the other boring dev tools in the space.
e.g.
best-of-breed
Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, and optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims.
bleeding edge
Do not use.
boil the ocean
Do not use. State exactly what you mean, such as "increase the scope hugely".
I.e. "increase the scope hugely", the word "scope" itself comes from greek with its core meaning revolving around "viewing" or "looking". It's only because we are all familiar with it also meaning the scale / amount of things a project should cover, that we all understand. (I guess there's a metaphor of the project "looking over" more as the number / magnitude of goals increases.)
So it shouldn't be "state exactly what you mean", because they are.
It should be more like: "state what you mean using widely used language if possible"
* "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.
Many times, a user receives communication from a single writer. This could be a consulting arrangement, or a small company, or any number of cases really. Those users are probably going to be consistent with themselves anyway, so there’s less need to be as specific on the small stuff. In that case a guide is really just trying to knock off the obvious rough edges in someone’s writing to make sure they’re actually communicating the information.
It's a convention that most documents use a monospaced courier or monospaced grotesk as that typeface.
[EDITED to add:] I agree with the general point about distinguishing best practices from conventions, though. (But there are also intermediate possibilities. "Best practice for us because it fits with conventions we've become used to". "Best practice for us because of some peculiarity of us or our work, even though for other groups it might not be so good".)
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.
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.
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.
E.g. I am not surprised to read "Distance to the server is one of the factors that affects latency."
They got lost in the details.
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.
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...
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
> 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".
>This reads silly for another reason: websites don't... introduce things.
The way they're using "introduces" does feel awkward, but in general, it's fine to say that a website "introduces" something.
For example, the Homestar Runner website introduced the world to Strong Bad. Or Action Comics #1 introduced Superman. You wouldn't really say that the author of Action Comics #1 introduced Superman.
For example, "Or Action Comics #1 introduced Superman." immediately feels more awkward, the reason it's not quite as awkward as RedHat's example is because it's in-context and doesn't explicitly mention "website", so one could conceivably mistake it for a magazine instead (which I take it probably was/is, an online one specifically).
Using "website" like this is like suggesting they're a publication or a periodical of some sort, which is true for some, but not in general (e.g. news sites?), making it weird.
[0] https://www.stylemanual.gov.au/ [1] https://docs.divio.com/documentation-system/
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.
All of these had in-house printshops, so would have had some style guides even if just to provide consistency for internal use.
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...
There's a lot of terminology around just mental illness that we have decided to leave in the past. And, a lot of it is for good.
One benefit of changing our language is we get a second chance. We can be more specific, more fine-grained, or more accurate. For example, sanity check is vague. If it's a bound check, we might say bounds check. That's more accurate. If it's a consistency check, we might say consistency check.
We want our language, particularly in technical pieces, to be both inclusive and precise. What I mean is, we want it to include every thing it should, and nothing it shouldn't.
For example, in Medical literature you'll often see the term "pregnant person" or "pregnant people", or even "people who may be pregnant". At first glance, it seems stupid. Why not just say "women"? Women is imprecise. There's a variety of people who would not identify as a woman who may be pregnant. If they get, say, a form with that verbiage they might mark "no, I'm not a woman". But they SHOULD mark "yes, I am a pregnant person" or "yes, I am a person who may be pregnant". It doesn't even just include transgender individuals - it also includes people born intersex, or people born without a uterus who do identify as a woman. There's women who may be pregnant and women who may never be pregnant, just as there are people who do not identify as women who may be pregnant. The word "woman" is then imprecise, confusing, and includes people it shouldn't, as well as excluding people it should.
This way leads to people writing blog posts about firing workers they don't employ because they used gender non-neutral language in technical posts.
Those cannot get pregnant. What's the point here? It's obvious that the phrase "pregnant woman" does not imply all women are pregnant.
Meaning yes, not every woman can get pregnant, but also not every pregnant person may identify as a woman. Suppose an intersex person born with a uterus who is pregnant but has lived their entire life as a man.
Definitely not something I'd force onto others either though.
There are a lot more people who would fail that test and be offended when pointed out. That group includes some forms of mental illness as well.
>"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).
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.
Looking forward to your model/product!
P.S. https://www.gov.uk/guidance/style-guide/technical-content-a-... also looks useful
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.
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 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.
at worst a regwall.
For the record I think Red Hat shouldn't put those behind a login, but that's a different argument
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?
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.
The docs are on https://docs.redhat.com/
RedHat's style guide is far more detailed and closer to a reference/explanation (i.e. going by Diátaxis definition).
Google's technical writing is shorter and closer to tutorial/how-to guide.
I recommend the Google's technical writing if you're a coder or a beginner. RedHat is for folks who already know they need this on first look.
Your answer is perfect, thank you!