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.

I understand having both, particularly in an industry with many non-English native speakers.

I think it would be better to separate the advice as you suggest. Opinionated, or organization-specific, advice in one section and grammar in another.

Ensuring active voice and how to use possessives with product names is style.

"Who vs. Whom" is grammar.

I would even be okay with maybe including some "common" mistakes in the style guide if they are particularly prone in your field/organization--those are useful for even native speakers sometimes that confuse there/their/they're, etc. [0]

My qualm is that a "Style Guide" is about explaining "There are multiple ways to do this correctly, but this is what WE prefer." For example, "Prefer American spellings of color/favorite over British colour/favourite, etc."

But with basic subject-verb agreement, it's a requirement of the language and not really up for debate. If your subject doesn't agree with the verb in number and gender, IT ARE WRONG.

[0] https://www.oxfordinternationalenglish.com/common-english-gr...

> But with basic subject-verb agreement, it's a requirement of the language and not really up for debate. If your subject doesn't agree with the verb in number and gender, IT ARE WRONG.

I’m very confused about what you are talking about, when

> > There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here.

per this comment:

https://news.ycombinator.com/item?id=44524290

As you mention what is or isn’t up for debate, why do you keep bringing up to debate something that is explicitly referenced but not discussed or addressed by TFA? The author already beat you to the punch by opting not to debate that point, and that’s the one you specifically want to talk about?

Are you fishing for red herring? Color me confused lol

I don't need to fish, the subject-verb agreement was an example. Grammar points 2.2.1 (Pronoun-antecedent agreement, which they did feel the need to go into in detail) and 2.5 (Using Who, Whom, That, and Which Correctly) are other things I would consider "not up for debate".