←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
173 points jumpocelot | 3 comments | 10 Jul 25 15:01 UTC | HN request time: 0.415s | 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. 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(2): >>44527093 #>>44527725 #
2. Spooky23 ◴[11 Jul 25 00:08 UTC] No.44527093[source]▶
+1… tbh this is where technical writers really add value. Neutral tone and focus on the action add clarity.
3. 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.”