Morten Bo Johansen <[email protected]> wrote:
>
> On 2026-11-03 Larry Kollar wrote:
>
>> As I’ve gone through UTP and started modernizing,
>> and finding (or all too often, recreating) lost utilities,
>> I noticed several quirks that bothered me—overuse
>> of “will” and “simply,” and lots and lots of passive voice.
>> I fixed those that I noticed as I went through the book,
>> but obviously missed a lot more.
>
> Just a question: Do you intend to root out all use of passive voice?
I’m leaving comments and .ig blocks alone. I’ve identified a couple
of places where changing to active voice makes things more awkward,
and I’ll leave those. Everything else is fair game.
> Not being a native English speaker, my qualifications to weigh in on this,
> admittedly are somewhat limited.
That’s another goal for UTP Revisited: make it more relevant to
non-US readers. I’d love to have a good section on internationalization
and/or localization, for example. I did some “i18n," but it was a long
time ago and today’s tools are far beyond what I had to work with then.
(Is anyone familiar with a termbase, or terminology database? They do
have uses beyond internationalization. I have some thoughts about how
to use a termbase in CSV format, with an awk script, to check for proper
usage of terms… but that might be a UTP 2.1 project.)
> But I wonder if the use of passive voice is
> somehow grating to the ears of native English speakers? I don't feel that
> myself, but again ...different backgrounds.
Not so much native English speakers *in general*, but I explain my
stance farther down.
> As an example of one of your
> changes, you replace
>
> "The file is not changed until you save your changes"
>
> with
>
> "The file does not change until you save your changes"
>
> In the first formulation, it is indicated (more clearly, IMO) that it is an
> action that makes the file change (saving the file), so actually, I think
> that the use of passive voice is appropriate there. Duckgo'ing for
>
> "examples of passive voice in english"
>
> I get, e.g.:
>
> When to Use Passive Voice
>
> Passive voice can be useful in situations where the doer is unknown,
> unimportant, or when the action itself is more significant than the actor.
> It is often found in formal writing, such as scientific reports, where the
> focus is on the results rather than the researcher.
>
> Doesn't the UTP document fit that bill fairly nicely? It is arguably a
> scientific paper of sorts, describing the use of a complex computer program.
>
> Ultimately, it a question of whether the end goal of your project warrants
> the effort. ;)
Ha, true, but in this case I think it does. Since at least the mid-90s, 30+
years,
all of our style guides admonished us to minimize or eliminate the use of
passive voice. Since UTP’s primary audience is technical writers, they would
expect active voice. Indeed, they might wonder whether a book *aimed at them*
but larded with passive voice is serious.
There are two reasons, as I remember, for using active voice wherever possible:
1) (the primary one) It’s more direct, highlighting both the actor and the
action,
leaving nothing to chance.[1]
2) (secondary) In most cases, active voice constructs are shorter than passive
ones.
It’s still worth noting, though, as that reduces the cognitive load on the
reader.
And like I said (as does your citation), there are cases where passive voice
does
make sense. There are situations—and I’ve already run across a couple in UTP—
where rewriting a passive passage[2] results in a longer, more awkward sentence
that doesn’t work as well. Those I left alone. Like I said in my original post,
in
many cases it’s often a matter of replacing or deleting words; other cases
require
some word-shuffling.
So yes, I still want to do this—but I understand that we can’t eliminate passive
voice across the entire manual. A small handful of instances that we can’t
rewrite
shouldn’t hurt, though.
BTW, I’ve found that tacking the -w option onto grep reduces false positives
by forcing matches to conform to word boundaries:
$ grep -Enw '(is|are|was|were)( not)? [a-z]+ed’ *.t
I added a “passive” utility, basically a shell script with the above call to
grep, to
Writer’s ScriptBench[3]. I’m fiddling with an option to highlight the matched
portion
with color (—color=always since —color=auto doesn’t seem to do anything on
either OS X or Kubuntu).
— Larry
[1] I’ve run across a few UTP instances that had me scratching my
head, while trying to figure out who/what was responsible for the
action. Git and other source code control systems are a godsend for
these situations; someone else can look at the changes and maybe
point out that I erroneously decided actor A performed action X, not
actor D.
[2] Sorry, I couldn’t resist doing that.
[3] This lurched to life because so many of the utilities described in
UTP are unobtainium. I’ve found a few opportunities to extend WWB
as well. https://github.com/larrykollar/Writers-ScriptBench/tree/main
