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

RE: Top Ten Things You'd Like To Tell Engineers

Subject: RE: Top Ten Things You'd Like To Tell Engineers
From: lyndsey -dot- amott -at- docsymmetry -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 10 Aug 2004 23:28:48 -0400


Bob Colwell wrote:

So do your homework, make a glossary of the acronyms and made-up words they're using, and keep asking what they mean until you've got a map of the terrain.

My experience with engineers is that they are unable to help you with glossary definitions until you provide them with a list of definitions that you have, to the best of your ability, already written. Even then, a single engineer will not know if all your definitions are correct; you have to send the glossary to more than one person to ensure that all the definitions get checked. And even then, the glossary still probably contains a handful of definitions that have not been verified because the regular joe engineers just don't know if they are correct. At this point, you might need to ask a big-picture person such as the system architect to verify the last few terms. Occasionally, I have had to remove a term from the glossary and recast a few sentences in the documentation because no one could tell me if the definition was correct.
I have found that asking an engineer to define a term is like asking someone to define the meaning of life in three short sentences. For an engineer steeped in the technology of the company, a single term holds so many nuances of meaning that it cannot be defined in simple terms.
I have also found that when you provide the engineers with a complete glossary, they are more than happy to check it as long as it is written to the best of your ability. The more effort you put into researching the terms and defining them succinctly, the likelier it is that the engineers will see the value of the work. I once read a book on networking and several of the Open Systems standards just to write a short definition for CMISE; defining CORBA in one small paragraph just about killed me.
To my mind, the job of the engineer is not to always provide us with the answers to our questions, but to confirm whether our conclusions are true, whether we have accurately understood this small part of the application. So, before I go to talk to an engineer, I have usually figured out one or two possible answers to my question. Right or wrong, they generally elicit a conversation that is meaningful and on topic.
~~~~~~~~~~~~~~~~~~~~~
Lyndsey Amott
www.docsymmetry.com
Winnipeg, MB R3G 2J3

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

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: RE: Microsoft pays dear[ly] for insults through ignorance
Next by Author: Re: Word doc - footnotes to Endnotes?
Previous by Thread: Re: Top Ten Things You'd Like To Tell Engineers
Next by Thread: RE: Top Ten Things You'd Like To Tell Engineers

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

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

Sponsored Ads