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.
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.
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?
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...
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".
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.
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.
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).
> 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.
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."
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.
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?
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.
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.
> 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.
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.
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?
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.
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.
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.
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.
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 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.
5 replies →
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.
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.
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.
2 replies →
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.
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)
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.
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...
People also notice your work if done badly in accounting, security, QA.
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/rgt4Y
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.
2 replies →
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.
1 reply →
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.
2 replies →
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).
1 reply →
Active voice makes it clear who or what is performing the action. “The connection is then terminated” vs. “The client terminates the connection.”
2 replies →
+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...
3 replies →
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. ;)
3 replies →
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.
2 replies →
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...
> 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?
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.
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.
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/
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.
3 replies →
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.
13 replies →
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?
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.
1 reply →
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.
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.
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.
4 replies →
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.
13 replies →