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.
Subject:RE: Coordinating Field Defs and Procedural Info From:"Hickling, Lisa (TOR)" <lhickling -at- Express-Scripts -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 8 Nov 2006 09:17:38 -0600
[LONG]
We take a lot for granted about the way we write. We never usually have
to justify our approaches until someone else proposes a different path.
>From the comments received it appears though that there is at least some
method in my particular brand of madness.
Thanks to everyone who weighed in! I really appreciate your comments.
Here are the key considerations in presenting the case for separate
field descriptors complemented by separate, thin, task oriented procs:
Paul (for the challenging approach):
Field-level info in a procedure and concept info in the overview
Damien:
Description of each tab - what the tab does with the fields laid out in
a table, field, description, permissible values etc as required +
Straight procedural steps with minimal info and refs back to relevant
sections for more details. Occasionally have duplication if I feel
there's too much jumping back and forth.
Bear:
procedural steps as concise as possible. + If the field requires
definition we do that either in the preamble leading up to the steps, or
in a table that could precede or follow the steps.
Tracy:
field descriptions within a procedure makes the information buried. +
In an ideal world, the field descriptions would be embedded in the
application itself, perhaps available on hover over the field label, and
help would just be procedures, also available in a dedicated application
pane.
Jan:
The procedures include just enough information about the fields to
answer most any question the end-user may have when completing the
fields. Cross-references are included, when appropriate.
Janice
Where the field location is clear and the procedure has just followed
an explanation of the widgets that provide the information, then I
wouldn't provide any further information or links.
Diane:
I prefer giving the definitions prior to the procedure if adding the
definitions make the procedure long and complicated, or if the
definitions break the continuity of the procedure flow.
Linda:
Document separately and point to where needed: reusable info; info of
interest to only a smaller user subsets; and reference info. Other info
gets fully detailed on the spot.
If I'm missing anything please let me know.
Thanks,
Lisa
******* Confidentiality Notice *******
ESI Canada -- Optimizing the value of drug and dental benefits
This email, its electronic document attachments, and the contents of its website linkages may contain confidential health information. This information is intended solely for use by the individual or entity to whom it is addressed. If you have received this information in error, please notify the sender immediately and arrange for the prompt destruction of the material and any accompanying attachments.
******* Avis de confidentialite *******
ESI Canada -- Optimiser la valeur des regimes d'assurance medicaments et dentaires
Ce courriel ainsi que tout document y etant joint de meme que le contenu des liens vers des sites Web peuvent reunir des renseignements confidentiels sur la sante. Cette information s'adresse uniquement a l'usager ou a l'organisation auxquels elle est destinee. Si vous avez recu ce message par erreur, veuillez en aviser l'expediteur immediatement et proceder a la suppression du document et des fichiers joints sans tarder.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-