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.
RE: Checking assumptions at the door (but NOT he vs she!)
Subject:RE: Checking assumptions at the door (but NOT he vs she!) From:Berk/Devlin <armadill -at- earthlink -dot- net> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 07 Jun 2001 09:52:11 -0700
On Wed, 6 Jun 2001 09:02:58 -0600, "Christensen, Kent" <lkchris -at- sandia -dot- gov> wrote:
>re: A former co-worker once decided she couldn't assume her readers knew X,
>then decided they also needed remediation on pre-X just in case, and finally
>decided she couldn't assume they even knew how to read. ... IMHO,
>assumptions are not necessarily Bad Things.
>
>Why, of course, but let's discuss the notion of *prerequisites* rather than
>assumptions. Like when you get into umpty-ump 102 only when you've had 101.
>There's an assumption in there, for sure, but ... . Seems to me that if
>your software requires Windows 98, or something, then ability to run Windows
>98 is a prerequisite and not to worry. ...
I am writing a series of manuals about a Java 2 Enterprise Edition (J2EE) product from scratch.
First thing we did was discuss who our readers would be and what kinds of skills they would have. We decided that they would be Java programmers, but that they might not be up to speed on J2EE. So, now here we are pretty far along in manual development and I am trying to decide when to define terms in the text and/or add a term to the Glossary and when not to.
Even though we thought we had agreed on the level of our readers, we are disagreeing on like 80% of the possible terms.
Finally, we realized, we needed a bible. We agreed that if a word was in the O'Reilly Java book's index, we did not need to define it because it is in "standard Java". If it is not in the index, we do define it somewhere in our documentation.
The SMEs have been ASTONISHED at what all is not in that index. (I didn't choose the O'Reilly book; they did so it's not my fault.)
It is always something.
--Emily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~ Emily Berk ~
On the web at www.armadillosoft.com *** Armadillo Associates, Inc. ~
~ Project management, developer relations and ~
extremely-technical technical documentation that developers find useful.~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.com
---
You are currently subscribed to techwr-l as: archive -at- raycomm -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.
