Red Hat Technical Writing Style Guide

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.

Yeah, I was thinking the same.

They got lost in the details.

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.

> 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.

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...

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.

> 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. ;)

+1… tbh this is where technical writers really add value. Neutral tone and focus on the action add clarity.

Looks right to me. Are you referring to the capitalization?

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.)

> 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.

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.

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).

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.

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.

Unfair comparison. It would be:

“The connection is terminated by the client.”

Which is just as clear.

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".

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.