←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
265 points jumpocelot | 1 comments | 10 Jul 25 15:01 UTC | HN request time: 0.211s | 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 #
kevin_thibedeau ◴[10 Jul 25 19:31 UTC] No.44524658[source]▶
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.
replies(3): >>44527093 #>>44527725 #>>44531081 #
russfink ◴[11 Jul 25 01:58 UTC] No.44527725[source]▶
Active voice makes it clear who or what is performing the action. “The connection is then terminated” vs. “The client terminates the connection.”
replies(2): >>44530555 #>>44532140 #
1. Y_Y ◴[11 Jul 25 10:32 UTC] No.44530555[source]▶
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.)