←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
262 points jumpocelot | 5 comments | 10 Jul 25 15:01 UTC | HN request time: 0.917s | 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(6): >>44524184 #>>44524285 #>>44524290 #>>44524658 #>>44526636 #>>44531050 #
1. dmurray ◴[10 Jul 25 22:57 UTC] No.44526636[source]▶
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."

replies(1): >>44526951 #
2. scoot ◴[10 Jul 25 23:46 UTC] No.44526951[source]▶
And I'm not surprised to see "e.g." being used incorrectly. ;)
replies(2): >>44527688 #>>44531090 #
3. ruraljuror ◴[11 Jul 25 01:52 UTC] No.44527688[source]▶
Looks right to me. Are you referring to the capitalization?
4. Cthulhu_ ◴[11 Jul 25 11:53 UTC] No.44531090[source]▶
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.

replies(1): >>44533547 #
5. red-iron-pine ◴[11 Jul 25 15:49 UTC] No.44533547{3}[source]▶
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.