RE: introducing steps

Subject: RE: introducing steps
From: "Porrello, Leonard" <lporrello -at- illumina -dot- com>
To: 'Phil Stokes' <philstokes03 -at- googlemail -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 18 Oct 2011 16:59:49 +0000

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.



-----Original Message-----
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.


Phil

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
> independent sentence.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
http://www.doctohelp.com

---
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:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
introducing steps: From: Becca
RE: introducing steps: From: Peter Sturgeon
Re: introducing steps: From: Phil Stokes

Previous by Author: RE: STC certification program
Next by Author: RE: introducing steps
Previous by Thread: Re: introducing steps
Next by Thread: Re: introducing steps


What this post helpful? Share it with friends and colleagues:


Sponsored Ads