RE: Basic structure question

["Ruiter, Vicki" <Vicki_Ruiter -at- sra -dot- com>]

My first knee jerk reaction is that the management of the object is a
separate area from the creation, and presumably done after the creation.
The maintenance description can probably be pulled to its own section.  The
next question is: will all of your readers need to read through the full
descriptions?  Or will some of them already come to this process knowing
what they need?  Are you doing a disservice to these "clued" readers if you
include pages of discussion for those without a clue?

Without knowing any particulars and knowing if this is something that would
work, I would probably create a matrix for each option, condensing the
issues down (including the management issues, if that is something that
needs to be considered in the creation). I'd make it something akin to what
you might look at to determine if you need a standard, professional or
enterprise version of a software.  Do I need to x, y, and z? okay, what
option do I choose to allow me to do this? what implication does that have
for management?  That sort of thing. The placement of the full descriptions
would depend on the level of user. If I expect that most would know what
these things are, I might include it as an appendix. If it's integral in the
functioning of whatever and people are unfamiliar with it, I might include
it up-front.....

Vicki Ruiter
SRA International, Inc.
 

-----Original Message-----
From: Lulu TW
To: TECHWR-L
Sent: 10/16/03 5:51 AM
Subject: Basic structure question


Hi all,

I'm returning to tech writing after a sabbatical, and although I'm
finding 
that most of the necessary info is still lodged somewhere in the grey 
matter, I'm having problems with a basic structuring issue.
The problem is this:
I'm writing an Admin Guide, and one section is wholly taken up with
creating 
an object. Now, to create this object, you just open a tool, select the 
object, and the object creation dialog box appears. In this dialog box, 
there's 13 different property fields to be set...but, explaining each 
property involves major discussion of what it is, whjat it does, how to 
manage it etc (going up to five or six pages worth of description in
some 
cases). So...I'm wondering whether to describe and explain each property

separetly first before explaining the object creation procedure, or
whether 
to describe and explain each property sequentially as it is displayed in
the 
object creation dialog box, with all the interruptions to the object 
creation procedure that this would involve.

What do you guys reckon?

Thanks,

Lulu

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

HAVE YOU SEEN THE LATEST FRAMEMAKER PUBLISHING TOOL?

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.  
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for 
competitive pricing or view a live demo at: http://www.ehelp.com/techwr-l3

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