Red Hat Technical Writing Style Guide(stylepedia.net) |
Red Hat Technical Writing Style Guide(stylepedia.net) |
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
I suspect his silly and fun-sounding "kinda drunk" brand voice was what set them apart from all the other boring dev tools in the space.
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?
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
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".
“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...
* "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.
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".
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.
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.
> 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".
> 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 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.
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.
But maybe I'm overthinking it too much. I prefer reading.
"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
https://www.google.com/books/edition/The_IBM_Style_Guide/77W...
All of these had in-house printshops, so would have had some style guides even if just to provide consistency for internal use.
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?
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...
Definitely not something I'd force onto others either though.
>"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).
[0] https://www.stylemanual.gov.au/ [1] https://docs.divio.com/documentation-system/
> 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".
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.
RedHat's style guide is far more detailed and closer to a reference/explanation (i.e. going by Diátaxis definition).
Google's technical writing is shorter and closer to tutorial/how-to guide.
I recommend the Google's technical writing if you're a coder or a beginner. RedHat is for folks who already know they need this on first look.
Your answer is perfect, thank you!
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.
Many times, a user receives communication from a single writer. This could be a consulting arrangement, or a small company, or any number of cases really. Those users are probably going to be consistent with themselves anyway, so there’s less need to be as specific on the small stuff. In that case a guide is really just trying to knock off the obvious rough edges in someone’s writing to make sure they’re actually communicating the information.
It's a convention that most documents use a monospaced courier or monospaced grotesk as that typeface.
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.
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.
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 think it would be better to separate the advice as you suggest. Opinionated, or organization-specific, advice in one section and grammar in another.
Ensuring active voice and how to use possessives with product names is style.
"Who vs. Whom" is grammar.
My qualm is that a "Style Guide" is about explaining "There are multiple ways to do this correctly, but this is what WE prefer." For example, "Prefer American spellings of color/favorite over British colour/favourite, etc."
But with basic subject-verb agreement, it's a requirement of the language and not really up for debate. If your subject doesn't agree with the verb in number and gender, IT ARE WRONG.
[0] https://www.oxfordinternationalenglish.com/common-english-gr...
E.g. I am not surprised to read "Distance to the server is one of the factors that affects latency."
They got lost in the details.
Googling now, that usage is often referred to as using commas to offset a non-essential clause.
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.
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.
The most reliable non-fine-tuned method I have seen is to do many, many passes over the doc, instructing the LLM to focus on only one rule during each pass.
Looking forward to your model/product!
P.S. https://www.gov.uk/guidance/style-guide/technical-content-a-... also looks useful
And here are its style comments: https://gist.github.com/stevelandeydescript/a586e312c400769b...
I don't plan to release the code, since I don't really want my docs to be written in this voice. But it doesn't feel entirely unhelpful, as long as I'm personally curating the changes.
I recently produced a bunch of migration guides for our project by pointing Claude 4 Sonnet at my poorly structured Obsidian notes (some more than 5 years old), a few commits where I migrated the reference implementation, and a reasonably well-maintained yet not immediately actionable CHANGELOG. I think the result is far from top-notch but, at the same time, it is way better IMO than nothing (nothing being the only viable alternative given my priorities): https://oslc.github.io/developing-oslc-applications/eclipse_...
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.
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.)
“The connection is terminated by the client.”
Which is just as clear.
Four and half years later, I'm still employed as a professional Go programmer.
Thanks, Brian!
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.
[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".)
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.
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.
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.
Both would work in this case, but e.g. is not incorrect.
id est is literally "that is". For something like "OP is a bakchod; that is, a tosser" -- replace that is with i.e.
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
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.
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.
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.
There's a lot of terminology around just mental illness that we have decided to leave in the past. And, a lot of it is for good.
One benefit of changing our language is we get a second chance. We can be more specific, more fine-grained, or more accurate. For example, sanity check is vague. If it's a bound check, we might say bounds check. That's more accurate. If it's a consistency check, we might say consistency check.
We want our language, particularly in technical pieces, to be both inclusive and precise. What I mean is, we want it to include every thing it should, and nothing it shouldn't.
For example, in Medical literature you'll often see the term "pregnant person" or "pregnant people", or even "people who may be pregnant". At first glance, it seems stupid. Why not just say "women"? Women is imprecise. There's a variety of people who would not identify as a woman who may be pregnant. If they get, say, a form with that verbiage they might mark "no, I'm not a woman". But they SHOULD mark "yes, I am a pregnant person" or "yes, I am a person who may be pregnant". It doesn't even just include transgender individuals - it also includes people born intersex, or people born without a uterus who do identify as a woman. There's women who may be pregnant and women who may never be pregnant, just as there are people who do not identify as women who may be pregnant. The word "woman" is then imprecise, confusing, and includes people it shouldn't, as well as excluding people it should.
This way leads to people writing blog posts about firing workers they don't employ because they used gender non-neutral language in technical posts.
"Pregnant person" is the least specific, "pregnant woman" is the most specific.
Those cannot get pregnant. What's the point here? It's obvious that the phrase "pregnant woman" does not imply all women are pregnant.
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.
The docs are on https://docs.redhat.com/
at worst a regwall.
For the record I think Red Hat shouldn't put those behind a login, but that's a different argument
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.
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.
You're positing an opinion as statistical fact; the reality is that most people do not care.
It's not a login. It's a login with an active subscription. Are those article that valuable that they can't provide it for everyone with a @company.com address that has >n licences?
Pure speculation, but I'm guessing they view the knowledge base as part of "support" (or like level 1 or something), which is why they're so restrictive. I think they greatly underestimate the number of people like us though that already use RHEL but don't want to bother with accounts because we can get by without it, but would benefit from having the access. They don't seem to understand the friction their policies create, and I think that's deeply unfortunate.