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.
You can think of it in terms of tolerances. Beej's (and others you mention) style is like a tighter tolerance: it fits to better effect at the cost of fitting in fewer places.
Personally, I'm in the audience that that style works well on, but I can also see how it might be harder for someone to follow that style. e.g. if English isn't their native language. Similarly, I imagine that style is also much harder to localize (not just translate).
I think both techniques are great and I don't think they're mutually exclusive. That is, you can still inject flavor and style within the confines of a technical style guide. You just do so in a way that's less... flamboyant?
Absolutely on board with you and GP, I forgot Kernighan, I've only looked at a couple of chapters of the C Programming Language, but it was totally wonderful to read yes! He's definitely up there
I really should have included Bob Chassell, of "Intro to Emacs Lisp" fame, what a personable and gentle introduction for beginners! Very beginner-focused, but if you read it as a beginner, it's like your slightly chatty Uncle introducing you to the family business. Which just so happens to be - writing a lisp language to learn to extend a lisp software platform which includes a text editor. I loved it.
Extending the Interior Design metaphor, the context of what's being designed and for who, that is, the doc archetype (manual, tutorial/guide, reference, recipies/demos/samples, audience-specific), is the first important part to get right.
> technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally
why do people read docs ... because they want to achieve something ... you need to work out what problem your reader is trying to solve.
If Dusty wants to put their degree up on the wall, they might want to consult some documentation about how to do it. The documentation Dusty needs to do this would probably not be called "How to Choose a Drill". The documentation Dusty needs is "How to Hang a Picture".
That’s far from exclusive to interior design. Any designer in every discipline will be familiar with that notion, regardless of it being interior design, industrial design, graphic design, …
“Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible” — Donald A. Norman, The Design of Everyday Things (1988)
I was about to recommend an episode or two, but it's an institution at this point. If you have a reasoned opinion about flags, there's a reasonably good chance it's because you saw or heard Roman Mars talk about vexillology.
https://www.ted.com/talks/roman_mars_why_city_flags_may_be_t...
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".)
The convention is used also for strings entered in a proportional font such as an address bar. I think the primary reason for the convention is most fonts where all characters are distinct are monospaced. But terminals being monospaced typically contributed surely.
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.
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".
It makes sense too when you fully understand your audience isn't exclusively English; expressions will be more difficult to read for ESL, and difficult if not impossible to translate to a non-English language. And the docs site is available in 8 different languages.
With translation tools (from the past... 3 decades, starting with Babelfish) and modern-day documentation processing / retrieval tools (LLMs), simplicity, clarity and consistency are even more important. But it's timeless advice.
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"
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.
You'd think / hope / expect editors and IDE's would put squiggly underline's under incorrect apostrophe'd plural's, but ala's.
I always assumed it was mainly a thing with Dutch people who have English as a second language, given that using 's for plural's is common, also in words shared with English like baby's or ski's, but it seems to be an issue with English speaker's too.
There's one area where I also struggle with apostrophes and pluralization, that being acronyms which must be kept lowercase. Whenever I hit such a situation, I usually just reword the entire sentence just to avoid it.
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.
That aside, learning about english vs passive voice - and recognising it in your own writing - has been pretty important. I often find myself using passive voice in code reviews, like "maybe you should do xyz instead", but... if it's something I am certain about or feel strongly about, I should use active voice more. (note how the last sentence is still passive lol).
The phase "maybe you should do xyz instead" is active, not passive. Qualifying with maybe doesn't change it from active to passive. Passive would be something like "Maybe XYZ should be done" or "Maybe XYZ would be better".
Specifically, passive voice is what I'd choose when it is unclear or unimportant who the subject is. Maybe there's a race condition and the client or server may send a termination notice sepend on whose clock ran out first, but the result is (by design, ideally) exactly equal.
On the other hand, if there a a particular party that must terminate the connection, or which party does the termination will have a relevant effect (in the context of the text) it should be made clear through active voice.
(Of course you can skip passive and explain that it's immaterial who performs the action, but whether you want to go into that detail will depend on context.)
> what I would expect as a basic requirement for passing high school English?
You're making the assumption here that the reader / documentation writer has had high school English; the documentation is written by and for non-English natives, too, and available in 7 non-English languages.
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?
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."
e.g. means "example given", it's being used correctly in this case; i.e. is a bit more subtle as it's Latin for "id est", which is more like a "that is to say..."
Both would work in this case, but e.g. is not incorrect.
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.
Yeah it reads like one to file away if I ever end up doing a lot of technical documentation. In this case, it's a guide that is aimed at an army of people (dozens? Hundreds? I don't even know, Red Hat has 19.000 employees) writing documentation as their day job. That is, I wouldn't be at all surprised if just the number of people writing documentation for RH is more than the number of engineers we have at my current employer (one of the major energy companies in the Netherlands).
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?
It's also a very typical sentence structure taught in US English. I learned it around 7th grade where there's a huge push to teach formulaic ways to use commas properly instead of just sprinkling them everywhere in run-on sentences.
Googling now, that usage is often referred to as using commas to offset a non-essential clause.
Notably, because German has more articles and conjugations, this writing style is very clear and easy to follow in German, at least to native speakers.
> This reads silly for another reason: websites don't... introduce things. Website owners might.
That feels overly pedantic, and is incorrect. “Introduce” means “bring a subject to the attention of (someone) for the first time”. It doesn’t need to be done by a person.
It’s perfectly acceptable to say, for example, “The Shining introduced me to the horror movie genre”. That doesn’t leave room for doubt that you mean The Shining was your first horror movie. It would’ve been silly to say “Stanley Kubrick introduced me to the horror movie genre” just because you watched one of his movies.
The keyword may be the same, but it's really not the same intended meaning.
> It doesn’t need to be done by a person.
Not entirely what I was trying to suggest, but that it's usually an organization, a project, or a specific person who introduces things, and that I'm not sure how to pin this semantic category down. In the example sentence, "RedHat" or "the OpenShift project" would have been much better choices I'd say for example. Consider:
> The OpenShift project introduces the Developer Center, a new section to the OpenShift website dedicated to reference materials and other resources.
>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.
Why do they have this in the list of examples of 'run-on sentences':
> Bad: To access your programs click the Start button.
> Improvement: To access your programs, click Start.
Sure, the improved version has added a comma, but the initial version is not a 'run-on sentence'; it does not contain 'two or more complete ideas that are joined without punctuation'. The comma here is completely intonational; it would not be needed if the word order was different, as in 'Click Start to access your programs'.
Anyone know why this was removed? It matches my training as a public-school student in the US, including in college while working on my Bsc in the natural sciences.
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.
I refuse to use the word "simple" in my docs writing for this precise reason. I have come to view the word to seem condescending/elitist, even if that's not the intent.
If something is written as simple, but I as an entrant to something view it as not simple, I'm going to be severely discouraged - "if this is the simple thing, what is the hard thing?"
Same in spoken word; I don't know if this is a regional (western European, expat-English) thing, but a lot of people will interspers their spoken sentences with "basically" and "actually" a lot. It's gratuitous and more of a verbal tic than something that adds to their sentence.
But maybe I'm overthinking it too much. I prefer reading.
Depending on where the emphasis is (which there is none in written form), it could be read as:
"How to connect to network resources simply? By authenticating to their local machine" (which I think is how you interpreted it)
or "How to connect to network resources? Simply by authenticating to their local machine" (which I think is what was meant)
The ambiguity itself is a good enough reason to not use this form. If the former was meant, say "the simplest way to connect to network resources is ...", otherwise just drop the "simply" as suggested
Bit weird that correct use of the language is part of a style guide. Perhaps this particular mistake happens often enough they felt the need to codify it?
> 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...
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.
Don't people who "fail a smell test" and get offended do so because they they think it's a propestourous claim they're failing it? It's kind of the opposite situation, cause wouldn't that make them not take it on themselves by default and thus not wish for the nonuse of this phrasing?
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.
Sounds like victim blaming to me; who are you to decide what is healthy or fair for someone else, or what words are offensive or harmless?
Because I can guarantee there's words that would make you upset if they were used against you. I mean this thread is because someone had an emotional response to "inclusive language", they zoomed right in on it and ignored every other aspect of the thing, even calling for the whole section to be removed.
How is that different? I don't understand why people get so upset about inclusive language. 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.
> I mean this thread is because someone had an emotional response to "inclusive language", they zoomed right in on it and ignored every other aspect of the thing, even calling for the whole section to be removed. How is that different?
Great, you win, it's not different. The person getting upset at "inclusive language" is on the same level as the one getting upset at "sanity check" because everyone's offended by something and therefore all offense is equal. What now?
Nice try turning it around, but no, you didn't find a gotcha. You just tried to argue two opposites ("no amount of offense is unreasonable" and "the people I disagree with are the unreasonable ones") at the same time. You acknowledged there's a line and failed to address its location.
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.
"Pregnant woman" is more precise than "pregnant person" or "pregnant female“. Pregnant woman specifies the gender as well as implying the sex (female or intersex, since males lack a uterus), while "pregnant person" only implies sex and "pregnant female" specifies the sex but not the gender.
"Pregnant person" is the least specific, "pregnant woman" is the most specific.
It's less accurate for the reasons you listed: it includes gender, which isn't always accurate and is unnecessary.
The problem is that there are trans men who exist, who may be pregnant. If asked if they are a woman or a woman who may be pregnant, they would answer no, which is incorrect in the larger context.
Pregnant people is naturally a superset of pregnant women, so pregnant women WOULD be more precise, if the advice applied only to pregnant women, which it almost never does. So that means we should almost never use pregnant women, as it's inaccurate.
Specificity should not be sought in the face of inaccuracy. For example, "brick house" is more specific than "house". So if I said "I live in a brick house", that should be better right? No, because it's wrong - I live in a wood house.
Per my original comment: "we want it [terms] to include every thing it should, and nothing it shouldn't." Pregnant woman doesn't include everything 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.
Love seeing that section, hate people who unironically call themselves one of those phrases. I used to know one guy who integrated his karate hobby into his personality as an agile consultant... it was kinda embarrassing.
It seems you have a certain hyperfocus on inclusivity being mentioned, which is a shame; did you engage with the rest of the document with as much effort? Or do you have an agenda and/or an irrational emotional response to mentions of inclusivity?
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.
I was on Red Hat’s informal style committee (Word Nerds) which wasn’t specifically technical writing though we had technical writers on it. A lot was fairly detailed oriented stuff but we also covered more general topics.
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.
I see a future (actually it probably already exists but it's not as cool as the end products) in deeply customizable LLM learning sets, where you can tick boxes for things like "yes to include various writing style guides", "no to reddit comments", etc.
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_...
That’s the funny part, poorly written technical guides that breaks some of all these rules will be worth its weight in gold because you know a real human wrote it.
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.
Yet "whomever" is also the object of the preposition, "to".
Certainly, if we took the primary clause of the sentence and substite in any number of pronouns, you'd agree that the objective forms are correct:
The book belongs to whomever. Not "whoever".
The book belongs to her. Not "she".
The book belongs to us. Not "we".
I don't know the English grammatical rule for this situation, but it certainly seems reasonable to say that the dependent clause does not get to dictate the form of an independent clause.
"The book belongs to the person who purchased it last week". Not "whom".
I think it is reasonable to say that the object of the to is not "who(m)ever", but the entire clause "who(m)ever purchased it last week"; and that clause should follow normal subject/verb agreement.
Similarly:
* "I don't know who purchased the book last week", not "I don't know whom purchased the book last week."
* "This is the person who you said purchased the book last week", not "This is the person whom you said purchased the book last week."
I've done some digging, and Fowler, Partridge and Gowers all support my stance, so I'm fairly confident in it now.
Not irrelevant at all. The case of the relative pronoun is determined by its role in the relative clause, not by the role of the relative clause in the sentence as a whole.
See:
- H. W. Fowler, A Dictionary of Modern English Usage
Perhaps you'd like to share a slightly more specific reference?
After all, these books treat many topics. Without specific reference, one might uncharitably assume that you are attempting to simultaneously misdirect and appeal to authority.
The Fowler and Partridge works are both arranged alphabetically, and in each the relevant entry is headed “who and whom”.
In Gowers, it is chapter 9, “The Handling of Words”, section “Troubles with Pronouns”, subsection 15, “Who and whom”; in the edition I own (Pelican Books 1962, reprinted 1970), that can be found on page 206.
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.
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 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 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.
Ah, the Ballmer peak.
See also: Stephen King, Oscar Wilde, William Wordsworth.
"write drunk, proofread sober" - Ernest Hemingway
Comment drunk, revise never!
https://quoteinvestigator.com/2016/09/21/write-drunk/
Looks like it was Peter de Vries, but the hallmark of a good quip is shambolic attribution.
Hunter S Thompson, James Joyce, Charles Bukowski, John Fante, Knut Hamsun, ...
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.
You can think of it in terms of tolerances. Beej's (and others you mention) style is like a tighter tolerance: it fits to better effect at the cost of fitting in fewer places.
Personally, I'm in the audience that that style works well on, but I can also see how it might be harder for someone to follow that style. e.g. if English isn't their native language. Similarly, I imagine that style is also much harder to localize (not just translate).
I think both techniques are great and I don't think they're mutually exclusive. That is, you can still inject flavor and style within the confines of a technical style guide. You just do so in a way that's less... flamboyant?
Brian Kernighan cannot be topped. He is easy to read, succinct, clear, and sometimes funny.
I second this. Donovan and Kernighan's The Go Programming Language taught me enough about the language to get my first job in it in less than a month.
Four and half years later, I'm still employed as a professional Go programmer.
Thanks, Brian!
Absolutely on board with you and GP, I forgot Kernighan, I've only looked at a couple of chapters of the C Programming Language, but it was totally wonderful to read yes! He's definitely up there
I really should have included Bob Chassell, of "Intro to Emacs Lisp" fame, what a personable and gentle introduction for beginners! Very beginner-focused, but if you read it as a beginner, it's like your slightly chatty Uncle introducing you to the family business. Which just so happens to be - writing a lisp language to learn to extend a lisp software platform which includes a text editor. I loved it.
I wish the Chicago Style Guide or MLA was organized like this, freely available, and open source. It would be a boon for writers everywhere.
Extending the Interior Design metaphor, the context of what's being designed and for who, that is, the doc archetype (manual, tutorial/guide, reference, recipies/demos/samples, audience-specific), is the first important part to get right.
https://github.com/google/opendocs/tree/main/project_archety...
> technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally
https://www.thegooddocsproject.dev/tactic/ia-guide / https://archive.vn/rgt4YThat’s far from exclusive to interior design. Any designer in every discipline will be familiar with that notion, regardless of it being interior design, industrial design, graphic design, …
“Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible” — Donald A. Norman, The Design of Everyday Things (1988)
It's the origin of 99 Percent Invisible's name: https://99percentinvisible.org/
I was about to recommend an episode or two, but it's an institution at this point. If you have a reasoned opinion about flags, there's a reasonably good chance it's because you saw or heard Roman Mars talk about vexillology. https://www.ted.com/talks/roman_mars_why_city_flags_may_be_t...
Is it true? I think people are very vocal about good design (interior or not). If they are not loudly loving your design, then try again.
People also notice your work if done badly in accounting, security, QA.
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.
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.
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".)
The convention is used also for strings entered in a proportional font such as an address bar. I think the primary reason for the convention is most fonts where all characters are distinct are monospaced. But terminals being monospaced typically contributed surely.
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.
Especially since AI grammar tools automated B for years now.
Particularly satisfying to see this section calling out a lot of business jargon: https://stylepedia.net/style/#avoiding-confusing-language
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".
It makes sense too when you fully understand your audience isn't exclusively English; expressions will be more difficult to read for ESL, and difficult if not impossible to translate to a non-English language. And the docs site is available in 8 different languages.
With translation tools (from the past... 3 decades, starting with Babelfish) and modern-day documentation processing / retrieval tools (LLMs), simplicity, clarity and consistency are even more important. But it's timeless advice.
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"
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.
> 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.
You'd think / hope / expect editors and IDE's would put squiggly underline's under incorrect apostrophe'd plural's, but ala's.
I always assumed it was mainly a thing with Dutch people who have English as a second language, given that using 's for plural's is common, also in words shared with English like baby's or ski's, but it seems to be an issue with English speaker's too.
There's one area where I also struggle with apostrophes and pluralization, that being acronyms which must be kept lowercase. Whenever I hit such a situation, I usually just reword the entire sentence just to avoid it.
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.
That aside, learning about english vs passive voice - and recognising it in your own writing - has been pretty important. I often find myself using passive voice in code reviews, like "maybe you should do xyz instead", but... if it's something I am certain about or feel strongly about, I should use active voice more. (note how the last sentence is still passive lol).
The phase "maybe you should do xyz instead" is active, not passive. Qualifying with maybe doesn't change it from active to passive. Passive would be something like "Maybe XYZ should be done" or "Maybe XYZ would be better".
Active voice makes it clear who or what is performing the action. “The connection is then terminated” vs. “The client terminates the connection.”
I agree with you and GP.
Specifically, passive voice is what I'd choose when it is unclear or unimportant who the subject is. Maybe there's a race condition and the client or server may send a termination notice sepend on whose clock ran out first, but the result is (by design, ideally) exactly equal.
On the other hand, if there a a particular party that must terminate the connection, or which party does the termination will have a relevant effect (in the context of the text) it should be made clear through active voice.
(Of course you can skip passive and explain that it's immaterial who performs the action, but whether you want to go into that detail will depend on context.)
Unfair comparison. It would be:
“The connection is terminated by the client.”
Which is just as clear.
+1… tbh this is where technical writers really add value. Neutral tone and focus on the action add clarity.
> what I would expect as a basic requirement for passing high school English?
You're making the assumption here that the reader / documentation writer has had high school English; the documentation is written by and for non-English natives, too, and available in 7 non-English languages.
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.
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...
> 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
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?
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."
And I'm not surprised to see "e.g." being used incorrectly. ;)
Looks right to me. Are you referring to the capitalization?
Yes, breaking a single sentence in two, hence beginning a sentence with "E.g.". At least stylistically if not grammatically incorrect.
e.g. means "example given", it's being used correctly in this case; i.e. is a bit more subtle as it's Latin for "id est", which is more like a "that is to say..."
Both would work in this case, but e.g. is not incorrect.
e.g. stands for the latin exemplī grātiā aka exempli gratia, which the literal translation is "for sake of example"
id est is literally "that is". For something like "OP is a bakchod; that is, a tosser" -- replace that is with i.e.
Yeah, I was thinking the same.
They got lost in the details.
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.
Yeah it reads like one to file away if I ever end up doing a lot of technical documentation. In this case, it's a guide that is aimed at an army of people (dozens? Hundreds? I don't even know, Red Hat has 19.000 employees) writing documentation as their day job. That is, I wouldn't be at all surprised if just the number of people writing documentation for RH is more than the number of engineers we have at my current employer (one of the major energy companies in the Netherlands).
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?
It's also a very typical sentence structure taught in US English. I learned it around 7th grade where there's a huge push to teach formulaic ways to use commas properly instead of just sprinkling them everywhere in run-on sentences.
Googling now, that usage is often referred to as using commas to offset a non-essential clause.
Notably, because German has more articles and conjugations, this writing style is very clear and easy to follow in German, at least to native speakers.
> This reads silly for another reason: websites don't... introduce things. Website owners might.
That feels overly pedantic, and is incorrect. “Introduce” means “bring a subject to the attention of (someone) for the first time”. It doesn’t need to be done by a person.
It’s perfectly acceptable to say, for example, “The Shining introduced me to the horror movie genre”. That doesn’t leave room for doubt that you mean The Shining was your first horror movie. It would’ve been silly to say “Stanley Kubrick introduced me to the horror movie genre” just because you watched one of his movies.
Is that not an idiom? https://idioms.thefreedictionary.com/introduce+me+to
The keyword may be the same, but it's really not the same intended meaning.
> It doesn’t need to be done by a person.
Not entirely what I was trying to suggest, but that it's usually an organization, a project, or a specific person who introduces things, and that I'm not sure how to pin this semantic category down. In the example sentence, "RedHat" or "the OpenShift project" would have been much better choices I'd say for example. Consider:
> The OpenShift project introduces the Developer Center, a new section to the OpenShift website dedicated to reference materials and other resources.
I agree with you that these examples feel awkward
>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.
Why do they have this in the list of examples of 'run-on sentences':
> Bad: To access your programs click the Start button.
> Improvement: To access your programs, click Start.
Sure, the improved version has added a comma, but the initial version is not a 'run-on sentence'; it does not contain 'two or more complete ideas that are joined without punctuation'. The comma here is completely intonational; it would not be needed if the word order was different, as in 'Click Start to access your programs'.
I find it interesting that the changelog for the doc refers to removing guidance for the use of em dashes in 2024.
I tried tracing the history back in Github, and it seems that the intent was to prohibit the use of em dashes in normal prose:
> In technical content, use a dash to show a range. Otherwise, use a colon or other suitable punctuation. Do not use em dashes.
https://github.com/StyleGuides/WritingStyleGuide/pull/618
Anyone know why this was removed? It matches my training as a public-school student in the US, including in college while working on my Bsc in the natural sciences.
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.
In my experience, technical people tend to tag way too many topics with “simply”. It is usually best to get rid of the word.
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.
I refuse to use the word "simple" in my docs writing for this precise reason. I have come to view the word to seem condescending/elitist, even if that's not the intent.
If something is written as simple, but I as an entrant to something view it as not simple, I'm going to be severely discouraged - "if this is the simple thing, what is the hard thing?"
It's often an unnecessary adjective.
Fair. Context matters.
Same in spoken word; I don't know if this is a regional (western European, expat-English) thing, but a lot of people will interspers their spoken sentences with "basically" and "actually" a lot. It's gratuitous and more of a verbal tic than something that adds to their sentence.
But maybe I'm overthinking it too much. I prefer reading.
Fair.
Depending on where the emphasis is (which there is none in written form), it could be read as:
"How to connect to network resources simply? By authenticating to their local machine" (which I think is how you interpreted it)
or "How to connect to network resources? Simply by authenticating to their local machine" (which I think is what was meant)
The ambiguity itself is a good enough reason to not use this form. If the former was meant, say "the simplest way to connect to network resources is ...", otherwise just drop the "simply" as suggested
Does this conflict with the IBM Technical Style Guide?
https://www.google.com/books/edition/The_IBM_Style_Guide/77W...
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.
> Do not use an apostrophe to denote a plural.
Bit weird that correct use of the language is part of a style guide. Perhaps this particular mistake happens often enough they felt the need to codify it?
Section 4.6 is certainly ridiculous, but I suppose you can just ignore it.
> 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...
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.
> "smell test"
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.
Don't people who "fail a smell test" and get offended do so because they they think it's a propestourous claim they're failing it? It's kind of the opposite situation, cause wouldn't that make them not take it on themselves by default and thus not wish for the nonuse of this phrasing?
Are we just disregarding the differently-abled people who have a diminished sense of smell? /s
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.
Sounds like victim blaming to me; who are you to decide what is healthy or fair for someone else, or what words are offensive or harmless?
Because I can guarantee there's words that would make you upset if they were used against you. I mean this thread is because someone had an emotional response to "inclusive language", they zoomed right in on it and ignored every other aspect of the thing, even calling for the whole section to be removed.
How is that different? I don't understand why people get so upset about inclusive language. 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.
> I mean this thread is because someone had an emotional response to "inclusive language", they zoomed right in on it and ignored every other aspect of the thing, even calling for the whole section to be removed. How is that different?
Great, you win, it's not different. The person getting upset at "inclusive language" is on the same level as the one getting upset at "sanity check" because everyone's offended by something and therefore all offense is equal. What now?
Nice try turning it around, but no, you didn't find a gotcha. You just tried to argue two opposites ("no amount of offense is unreasonable" and "the people I disagree with are the unreasonable ones") at the same time. You acknowledged there's a line and failed to address its location.
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.
Yes, they evolve but only if wider society accepts it. And in this case, most people don't consider that it's reasonable to change the phrasing.
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.
> And in this case, most people don't consider that it's reasonable to change the phrasing.
You're positing an opinion as statistical fact; the reality is that most people do not care.
I think wider society has accepted it. For these terms in medical literature, they're already in use and have been for decades now.
This isn’t medical literature. What will you do when someone writes how they want and won’t conform to your opinion?
Nothing. I'm just explaining why words evolve and why we choose to use more precise language. If you want to be more vague I certainly won't stop you.
"Pregnant woman" is more precise than "pregnant person" or "pregnant female“. Pregnant woman specifies the gender as well as implying the sex (female or intersex, since males lack a uterus), while "pregnant person" only implies sex and "pregnant female" specifies the sex but not the gender.
"Pregnant person" is the least specific, "pregnant woman" is the most specific.
It's less accurate for the reasons you listed: it includes gender, which isn't always accurate and is unnecessary.
The problem is that there are trans men who exist, who may be pregnant. If asked if they are a woman or a woman who may be pregnant, they would answer no, which is incorrect in the larger context.
Pregnant people is naturally a superset of pregnant women, so pregnant women WOULD be more precise, if the advice applied only to pregnant women, which it almost never does. So that means we should almost never use pregnant women, as it's inaccurate.
Specificity should not be sought in the face of inaccuracy. For example, "brick house" is more specific than "house". So if I said "I live in a brick house", that should be better right? No, because it's wrong - I live in a wood house.
Per my original comment: "we want it [terms] to include every thing it should, and nothing it shouldn't." Pregnant woman doesn't include everything it should.
> people born without a uterus who do identify as a woman
Those cannot get pregnant. What's the point here? It's obvious that the phrase "pregnant woman" does not imply all women are pregnant.
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.
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).
Love seeing that section, hate people who unironically call themselves one of those phrases. I used to know one guy who integrated his karate hobby into his personality as an agile consultant... it was kinda embarrassing.
It seems you have a certain hyperfocus on inclusivity being mentioned, which is a shame; did you engage with the rest of the document with as much effort? Or do you have an agenda and/or an irrational emotional response to mentions of inclusivity?
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.
[0] https://www.stylemanual.gov.au/ [1] https://docs.divio.com/documentation-system/
Government resources are great, we frequently refer to the UK's design system too for... accessibility-maxxing? https://design-system.service.gov.uk/
I was on Red Hat’s informal style committee (Word Nerds) which wasn’t specifically technical writing though we had technical writers on it. A lot was fairly detailed oriented stuff but we also covered more general topics.
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.
Looking forward to your model/product!
P.S. https://www.gov.uk/guidance/style-guide/technical-content-a-... also looks useful
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...
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.
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 see a future (actually it probably already exists but it's not as cool as the end products) in deeply customizable LLM learning sets, where you can tick boxes for things like "yes to include various writing style guides", "no to reddit comments", etc.
It’s unclear to me how this could work with current training methods.
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_...
This doesn't create slop. It's just an automated editor. A linter for natural language.
That’s the funny part, poorly written technical guides that breaks some of all these rules will be worth its weight in gold because you know a real human wrote it.
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.
The example sentence "Red Hat releases no upgrade before its time." Should perhaps be "it's".
No, see https://www.merriam-webster.com/dictionary/ahead%20of%20one'...
It's not short for "it is" in this context, more like "of it", as in, "the time to update it"
From 2.5. Using Who, Whom, That, and Which Correctly:
> This book belongs to whomever purchased it last week.
That should be "to whoever", surely? The pronoun is acting as the subject of the verb "purchased".
Yet "whomever" is also the object of the preposition, "to".
Certainly, if we took the primary clause of the sentence and substite in any number of pronouns, you'd agree that the objective forms are correct:
The book belongs to whomever. Not "whoever".
The book belongs to her. Not "she".
The book belongs to us. Not "we".
I don't know the English grammatical rule for this situation, but it certainly seems reasonable to say that the dependent clause does not get to dictate the form of an independent clause.
But on the other hand:
"The book belongs to the person who purchased it last week". Not "whom".
I think it is reasonable to say that the object of the to is not "who(m)ever", but the entire clause "who(m)ever purchased it last week"; and that clause should follow normal subject/verb agreement.
Similarly:
* "I don't know who purchased the book last week", not "I don't know whom purchased the book last week."
* "This is the person who you said purchased the book last week", not "This is the person whom you said purchased the book last week."
I've done some digging, and Fowler, Partridge and Gowers all support my stance, so I'm fairly confident in it now.
Irrelevant. The original example given is in the dative case, so it has to be “whom”. It’s really as simple as that.
Not irrelevant at all. The case of the relative pronoun is determined by its role in the relative clause, not by the role of the relative clause in the sentence as a whole.
See:
- H. W. Fowler, A Dictionary of Modern English Usage
- Eric Partridge, Usage and Abusage
- Ernest Gowers, The Complete Plain Words
who are unanimous on this point.
Perhaps you'd like to share a slightly more specific reference?
After all, these books treat many topics. Without specific reference, one might uncharitably assume that you are attempting to simultaneously misdirect and appeal to authority.
The Fowler and Partridge works are both arranged alphabetically, and in each the relevant entry is headed “who and whom”.
In Gowers, it is chapter 9, “The Handling of Words”, section “Troubles with Pronouns”, subsection 15, “Who and whom”; in the edition I own (Pelican Books 1962, reprinted 1970), that can be found on page 206.
I'm somewhat disappointed that the 'Copyright © 2025 Red Hat, Inc.' line at the top didn't read 'Copyleft 2025 Red Hat, Inc.'
[dead]
“They” has been used as a singular pronoun for hundreds of years.
for the haters:
https://www.merriam-webster.com/wordplay/singular-nonbinary-...
I didn't read the article yet. Does anyone know if it's better than the Google one here? [https://developers.google.com/tech-writing/overview]
TLDR: which is better? it depends
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.
Ok I phrased it badly with "better", I wanted to know how they compare.
Your answer is perfect, thank you!
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_...
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.
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 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.
I dont think that google is indexing that without a login/subscription though. TIL.
> paywall
at worst a regwall.
"You need an active subscription" is paywall for me.
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.
(I’m a red hatter) anyone can get the Red Hat Developer subscription for free and get full access to the knowledge base.
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
you can grab a free dev sub and it unlocks the KB and quick fixes too. Unless that changed relatively recently.