Documenting field descriptions in printed documentation

Subject: Documenting field descriptions in printed documentation
From: Alyssa Fox <a -dot- fox -at- pentasafe -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 17 Sep 2002 13:41:48 -0500


Hello,

The group of writers where I work all document field descriptions
differently and we need to come up with a uniform way of doing this so all
of our documentation looks alike. 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.

2. Create a separate step for each field and its description in the
following format:
"In the Username field, enter the user name."

3. Create a separate step for each field and its description in the
following format:
"Username - Enter the user name."

4. Create a separate step for each field and its description in the
following format:
"Enter the user name in the Username field."

Are any of these preferred or standard, and if so, which one? If not, does
anyone have any suggestions as to a good solution for this?

We already have a specific character tag for fields, so that's not the
issue. What is the issue is how we document the description of those fields.

Thanks for your time,
Alyssa Fox

Alyssa Fox
VSM Technical Writer
PentaSafe Security Technologies, Inc.
713-523-1992 ext. 9695
http://www.pentasafe.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:

Previous by Author: RE: A grand, grand opening line...
Next by Author: Re:terminology question (and a bit of a rant)
Previous by Thread: re: Multiple help files in RoboHelp 2002
Next by Thread: Re: Documenting field descriptions in printed documentation


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


Sponsored Ads