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.
Nice clarification. You make an excellent point, and I totally agree regarding the "niceties."
I would have been contradicting myself only if I had left off the "literally", but nice try. ;-)
From: Phil Stokes [mailto:philstokes03 -at- googlemail -dot- com]
Sent: Tuesday, October 18, 2011 10:42 AM
To: Porrello, Leonard
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: introducing steps
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.
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><mailto: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. http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
