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.
Lulu TW, back in town, wrote:
> I'm returning to tech writing after a sabbatical...
> 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.
When I'm drafting this kind of topic, I usually start out by creating a
basic descriptive reference topic. Just paste in a screenshot, then after
that make a subheading for every item you see on the screen. Then fill in
whatever you know about each item. If you don't know something, put your
question right in the draft.
Then keep drilling into the system (and your SMEs) until you have a
comprehensive reference topic for the dialog. You may or may not keep this
reference topic in your final draft, but I find it very helpful just as an
aid while I am writing.
There are lots of questions you should ask about each data item. Where does
it come from? What does the system do with the value I enter here? What are
the consequences of entering A instead of B? etc.
One of the most important questions to ask about a dialog is "What happens
when I click OK (or Submit)? Make a list of everything that happens when you
submit the data. Be extremely literal in making this list, even if you have
to read the code to identify everything that happens. There will probably be
a lot of things that happen on the back end. Not that you have to *document*
at the code level, but as an analytical technique you need to know
everything before you can decide what to put in your admin guide.
Ask similar questions for every button/command... What happens when I click
this? Be literal.
As you are building out this reference topic, you will probably feel the
urge to explain certain concepts in more depth. That's when you should
create a new topic just for that concept.
When your procedure comes to a concept that needs to be further defined,
just cross-ref to your reference topic where appropriate.
If you keep going with this method, you will eventually have a collection of
reference topics, conceptual topics, and procedures. Just promote/demote
headings until the structure makes sense, and then... Viola, a manual!
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.
