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