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.


Previous by Author: Re: techwr-l digest: June 04, 2001
Next by Author: Functional specification templates
Previous by Thread: Re: Checking assumptions at the door (but NOT he vs she!)
Next by Thread: Use of Addendum or other suggestion?


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


Sponsored Ads