[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

Re: introducing steps

Subject: Re: introducing steps
From: Phil Stokes <philstokes03 -at- googlemail -dot- com>
To: "Porrello, Leonard" <lporrello -at- illumina -dot- com>
Date: Wed, 19 Oct 2011 00:42:22 +0700

Well, Leonard, if you understood what I meant that would be one criterion that my words made sense, so it is a little contradictory to say it "literally makes no sense", isn't it? :p

As to the substantial point, I think here you misunderstood. I feared the caveat "and other minor structural alternatives" would be misread as meaning 'not paying attention to grammar'. That's not what I meant at all.

I was referring to the debate among competing structures as someone (sorry, was it Laura?) pointed out may fit different situations. I was also pointing out that users needs are a significant determiner of successful interpretation. There's been plenty of research showing that users /*scan*/ texts for the parts that are relevant to their needs rather than read every word.

That was indeed the point someone else was making when they said users often skip straight down to procedures and miss out preliminary material. They scan and skip to what looks relevant, and the difference between one kind of header phrase or another is often irrelevant to their success. Rather clear layout, white space, appropriate keyword choices and clear structure within the procedural steps will be greater determinants of that, IMO.

Best

Phil


On 18/10/2011 23:59, Porrello, Leonard wrote:

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
RE: introducing steps: From: Porrello, Leonard

Previous by Author: Re: introducing steps
Next by Author: Re: The legalese pages
Previous by Thread: Re: introducing steps
Next by Thread: RE: introducing steps

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

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

Sponsored Ads