5 ms·

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 re

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.

Spooky23 1y ago
+1… tbh this is where technical writers really add value. Neutral tone and focus on the action add clarity.
russfink 1y ago
Active voice makes it clear who or what is performing the action. “The connection is then terminated” vs. “The client terminates the connection.”
- Y_Y 1y ago
  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.)
- Hendrikto 1y ago
  Unfair comparison. It would be: “The connection is terminated by the client.” Which is just as clear.
Cthulhu_ 1y ago
That aside, learning about english vs passive voice - and recognising it in your own writing - has been pretty important. I often find myself using passive voice in code reviews, like "maybe you should do xyz instead", but... if it's something I am certain about or feel strongly about, I should use active voice more. (note how the last sentence is still passive lol).
- RichardLake 1y ago
  The phase "maybe you should do xyz instead" is active, not passive. Qualifying with maybe doesn't change it from active to passive. Passive would be something like "Maybe XYZ should be done" or "Maybe XYZ would be better".

Spooky23 1y ago

+1… tbh this is where technical writers really add value. Neutral tone and focus on the action add clarity.

russfink 1y ago

Active voice makes it clear who or what is performing the action. “The connection is then terminated” vs. “The client terminates the connection.”

Y_Y 1y ago
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.)
Hendrikto 1y ago
Unfair comparison. It would be: “The connection is terminated by the client.” Which is just as clear.

Cthulhu_ 1y ago

That aside, learning about english vs passive voice - and recognising it in your own writing - has been pretty important. I often find myself using passive voice in code reviews, like "maybe you should do xyz instead", but... if it's something I am certain about or feel strongly about, I should use active voice more. (note how the last sentence is still passive lol).

RichardLake 1y ago
The phase "maybe you should do xyz instead" is active, not passive. Qualifying with maybe doesn't change it from active to passive. Passive would be something like "Maybe XYZ should be done" or "Maybe XYZ would be better".