←back to thread

186 points jumpocelot | 3 comments | | HN request time: 0.521s | source
Show context
AdmiralAsshat ◴[] 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 ◴[] 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 ◴[] No.44527093[source]
+1… tbh this is where technical writers really add value. Neutral tone and focus on the action add clarity.
3. russfink ◴[] 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.”