TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
"The system will create the specified directory if it does not exist"
is a quote from a programmer's guide I wrote and there is nothing
remotely confusing about it when read in context. Any good style
manual will include examples of proper use of the passive voice along
with examples that should be revised to make them active.
You use considerably more words than necessary without making the
meaning any clearer just to avoid using perfectly good English.
On Tue, Aug 8, 2017 at 1:04 PM, Lauren <lauren -at- writeco -dot- net> wrote:
> On 8/8/2017 9:18 AM, Robert Lauriston wrote:
>>
>> You're turning guidelines into superstitions.
>>
>> Overuse of the infinitive form of "be" might a hallmark of bad
>> writing, but sometimes it's the right choice. "Use bulleted lists,
>> which are easy to scan and more likely to be read."
>
> "Which"? I was taught in legal writing, "beware of the which-es." Your
> example would not be my choice. I would say, "Use bulleted lists because
> they are easy for the reader to scan and read." Also, when I first read your
> sentence, I thought you meant OCR and it is not true that bulleted lists are
> easier to scan with OCR.
>
>> Same goes for passive voice. "If the specified output directory does
>> not exist, it will be created automatically" puts the emphasis on the
>> directory. The point is that the user does not have to create it
>> manually beforehand. Nobody cares what creates it.
>
>
> I would not state the command like that. First, "it will be created" refers
> to something outside of the sentence and the reader is left to assume what
> that it is. I would specify what is creating the directory. The system, app,
> program, or whatever it is. I would say, "The system will create the
> specified directory if it does not exist."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
