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