: Re: Technical Documentation Voice Preference : "Active Voice" - "Passive Voice" - A Mixture of both We are working on a technical documentation project which includes the rewriting, modernization, restructuring,
Passive voice always sounds more 'professional', but a big reason people write that way by habit is because they want to avoid the subject - the actor. If you have an error message all about how the file templates/banff.html isn't found, it sounds goofy to use the first person, as if the software is speaking:
"I cannot find the file templates/banff.html"
Running through a bunch of alternatives, often feels similarly strange. So, we avoid stating the subject by using the passive voice:
"The file templates/banff.html cannot be found."
But imagine that you're reading instructions about making your way through a bureaucracy. You read this sentence:
"The application then has the applicant's license and registration number filled in." Are YOU supposed to fill them in? Or does it happen automatically? Are the numbers filled in for you, by someone in the bureaucracy? Whoever wrote it left that detail out.
I have had situations like that, and I continue reading forward, keeping the question in my mind, hoping I'll get a clue further on down as to whether I'm expected to do it or not. Everything I read has to be doubled: "If I fill in the numbers, then that means..., but if they fill in the numbers, then that means....". I've had many situations where I run into yet another similar ambiguity, and I have to carry around three or four cases in my head, plowing through the instructions, hoping for some clues that sometimes never come, because the author continues to write passive voice. Every passive sentence could become one of these fork situations that adds to the reader's mental load.
Remember, also, that nobody complains about bad documentation. They don't want to look stupid, they ask somebody, defeating the whole purpose of the docs you wrote. So just cuz you've done a lot of writing with passive voice, doesn't mean it was a good idea to do so.
More posts by @Martha805
: Is there a hemisphere-neutral way of specifying a season? I want to refer to the timeframe of Summer 2019 in the Northern hemisphere. However, the writing is intended for a global audience,
: Where best to insert images using Scrivener for ebook/kindle etc My father wrote a book in Word and I have edited/formatted it so it looks clean in PDF, but now I know that was a bad idea
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.