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.
We put the material in a paragraph format called "Note." (We're in FrameMaker, but the concept is the same no matter what the system, only the mechanics differ.)
Up in the manuals front matter (it actually appears in our safety section) we define a Note as a paragraph "intended to convey pertinent information about a task. It is not a procedural step." We place then either before or after the relevant paragraph in the procedure, depending on what makes the most sense.
For what it's worth, that definition is also a close match for the standard definition of a Note found in aviation and MIL-STD manuals.
Rick Lippincott, Technical Writer
American Science and Engineering, Inc. | www.as-e.com
829 Middlesex Turnpike | Billerica, MA 01821 USA | Fax +1-978-262-8702
Office +1-978-262-8807 | rlippincott -at- as-e -dot- com
-----Original Message-----
From: techwr-l-bounces+rlippincott=as-e -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+rlippincott=as-e -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Cardimon, Craig
Sent: Wednesday, October 09, 2013 11:54 AM
To: 'techwr-l -at- lists -dot- techwr-l -dot- com'
Subject: Question about "sidebars"
Morning, Whirlers,
How do you folks handle sidebar notes and info?
Let's say I'm working on Topic A in a user guide. I have information related to Topic A, but not directly.
This information doesn't really fit elsewhere, so it needs to be in Topic A, but stand out just a bit. I put this "sidebar" information in a table in Topic A.
Users should be aware of this information but not get hung up on it. I labeled the table as a "Note." Not sure what else to do here. Suggestions?
Cordially,
Craig Cardimon
Information contained in this e-mail transmission is privileged and confidential. If you are not the intended recipient of this email, do not read, distribute or reproduce this transmission (including any attachments). If you have received this e-mail in error, please immediately notify the sender by telephone or email reply.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
