←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
196 points jumpocelot | 2 comments | 10 Jul 25 15:01 UTC | HN request time: 0.001s | source
Show context
AdmiralAsshat ◴[10 Jul 25 18:40 UTC] No.44524146[source]▶
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.

replies(5): >>44524184 #>>44524285 #>>44524290 #>>44524658 #>>44526636 #
1. perching_aix ◴[10 Jul 25 18:57 UTC] No.44524290[source]▶
> 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.

replies(1): >>44524474 #
2. starkparker ◴[10 Jul 25 19:14 UTC] No.44524474[source]▶
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.