Re: Documenting field descriptions in printed documentation

Subject: Re: Documenting field descriptions in printed documentation
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 17 Sep 2002 12:10:39 -0700


Alyssa Fox wrote:

Following are some of the ways each of us
documents the field descriptions now:

1. Create a single step that says "Complete the following fields" then have
a table with the field names and the descriptions in it so all field names
are contained in one step.

I'd recommend this option. It's by far the most concise way. Whether you're concerned about the cost of printing extra pages or you want to make documents easy for people to scan for the information that they want, conciseness is always a virtue in tech-writing.

Add a list of tables after the ToC, and you've also saved yourself the trouble of documenting the interface separately from the tasks - yet another bit of conciseness.

Probably the only adjustment you might have to make is in cases in which there's a combo box of possible options - and, even then, all you will probably need to do is add some columns to the tables.

Tables are also useful when documenting command switches or options, or anything other repetitive information.

--
Bruce Byfield bbyfield -at- axionet -dot- com 604.421.7177
http://members.axion.net/~bbyfield

"I would be wise, but that I often see
The fox suspected whilst the ass goes free"
-Sir Walter Raleigh, "A Farewell to the Vanities of the World"


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Acrobat & FrameMaker Seminars: PDF Best Practices, FrameMaker-to-Acrobat
Advanced Techniques, FM Template Design, Single Sourcing with FrameMaker
in Brussels (Oct), and in Montreal & Dallas (Dec): http://www.microtype.com/1

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l

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



Follow-Ups:

References:
Documenting field descriptions in printed documentation: From: Alyssa Fox

Previous by Author: Re: FW: Interesting article on CBT
Next by Author: Re: Quick Reference Material in User Guide?
Previous by Thread: Re: Documenting field descriptions in printed documentation
Next by Thread: RE: Documenting field descriptions in printed documentation


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


Sponsored Ads