Re: introducing steps
Phil said "I think this is over-analysing" and "the niceties of infinitives, gerunds, verbiage and other minor structural alternatives are not going to get in the way of the reader finding the content they came looking for"
Two things strike me about Phil's thoughts. First, I have no idea what "over-analyze" means in a technical context. I could understand mis-analyze (were there such a word), but over-analyze, as popular at the phrase is, literally makes no sense, does it? (To be fair, I think I know what Phil meant. I think he meant something like, "I think you are being overly pedantic.")
Second, I have had several experiences as an end-user in which disregard for grammatical and stylistic "niceties" have gotten in my way. A user who is learning a new process or implementing a system for the first time is already working hard to overcome the cognitive dissonance that almost always accompanies uncertainty. By the time the user turns to a user's guide, there is a very good chance that he is confused. By giving him grammatically and stylistically unrefined documentation, you only add to the cognitive and emotional burden he is carrying and push him further away from success and sanity.
Technical writing needs to be as transparent as possible, and you cannot write transparently without attending to grammatical and stylistic niceties.
From: techwr-l-bounces+lporrello=illumina -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lporrello=illumina -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Phil Stokes
Sent: Tuesday, October 18, 2011 8:47 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: introducing steps
I think this is over-analysing. It makes perfect sense from a language teachers point of view (or even from the POV of a language learner using technical docs for study material - yes, I've done that!).
However, users bring their own needs to a document, and if they're looking at a doc to find out how to do something, the niceties of infinitives, gerunds, verbiage and other minor structural alternatives are not going to get in the way of the reader finding the content they came looking for.
On Tue, Oct 18, 2011 at 6:28 AM, Peter Sturgeon<prsturgeon -at- bell -dot- net> wrote:
This thread ignores translation. Making the introductory phrase a complete
grammatical sentence makes it easier for translators and non-native speakers
of English to understand the procedure.
By starting with a infinitive phrase, every subsequent step is
grammatically part of a potentially very long serial sentence.
By starting with a complete grammatical sentence, each step acts as an
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com
To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.
Please move off-topic discussions to the Chat list, at:
- RE: introducing steps, Porrello, Leonard
Search our Technical Writing Archives & Magazine