Re: Grammar? YES!

["Diane Brennan (Write Stuff)" <a-dianeb -at- MICROSOFT -dot- COM>]

Tony, this is a hilarious example of technical writing errors!

I think your point is well taken that some technical writers believe that it
is more important to write documentation that is technically accurate and
complete than to write documentation that is comprehensible and easy to
read.  The reality is that we must do all these things or risk confusing the
reader.

I like the sentence construction you use in your example, where "such" is
referring to the direct object in the previous sentence.  I've seen this
confusing construction several times in documents written by programmers.
Then there's the obvious mistakes:  incorrect hyphenation, missing
punctuation, spelling errors, typos.  Did you pull these examples from a
real document?

Thanks for the laugh!

Diane

> Tony Markatos responds to Dan Wise (see Dan's original posting below)
>
> I write procedural infor. for software systems.  I say that there are a
> lot of grammar rules that can be disregarded in creating such.  I base
> my case on the following:
>
> 1.)  I write very good procedures.  In fact, compared to other writers
> whose work I have been exposed to, I write excellent procedures.  (Note:
> I am exceptionally strong in end user task analysis)
>
> 2.)  I know little about grammar (engineer by training).  I can go to
> any public library and check-out a 250 page book on grammar.  Of those
> 250 pages, I know about 75 pages worth.  The rest is Greek to me.  What
> are the contents of those 175 pages?  Until I have a need-to-know, I
> don't care.
>
> 3.)  I all the procedure writing that I have done, I can not recall a
> single instance in which grammar was an obstacle.
>
>
> Dan Wise wrote:
>
> Colleagues,
> >
> Geoff Hart raised the question of whether there are any grammar "rules"
> we can discard with TW/procedures.  Like Geoff, I can't think of any.
> Whether you are writing narrative, exposition, or imperative
> instructions, the same rules apply.  Or at least they have in all the 40
> years of writing I have done so far.
>
> No, I have not whipped out *kewl* Web pages for clients.  Nor have I
> experienced the joys and agonies of developing screen-size bites for
> on-line help/instruction.  My expertise is in paper copies of generally
> lengthy documents dealing with scientific and engineering projects.  And
> I have written reams of engineering and administrative procedures, but
> never software operating procedures.
>
> So, within the framework of my personal experience, I have to conclude
> that grammar does count if you expect to operate within a frame of
> mutual comprehension and understanding.
>
> >Dan Wise
> danwise -at- mindspring -dot- com
>
>
>
>
>
> ______________________________________________________
> Get Your Private, Free Email at http://www.hotmail.com
>
>
> ~
>