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: Question about "sidebars" From:Shawn C <shawn -at- cohodata -dot- com> Date:Wed, 9 Oct 2013 12:29:25 -0700
I agree with Paul.
I would replace the word "note" with a non-copyrighted universally
recognized note symbol for several reasons:
- "Note" takes up too much space
- Icon works better if you ever localize your content
- Icon simply looks better (IMHO)
My general rules for sidebars:
- Keep them succinct
- Minimize them, where practical, in HTML output (PDF - just keep them
- I prefer placing them in a shaded table (either stretched across page or
in a special side-bar margin).
But always be consistent! In other words, don't change the style
throughout a family of documents.
- Use icons to identify the sidebar theme (i.e. warnings, FYIs, notes,
- Your icons can either be self-created or open source - Avoid stealing!
Just don't do that.
- Try to minimize the number of sidebars in a document (unless you are
writing a For Dummies themed book, where a million sidebars probably work).
Hope this helps.
On Wed, Oct 9, 2013 at 9:02 AM, Cardimon, Craig <ccardimon -at- m-s-g -dot- com> wrote:
> Not sure MadCap Flare offers note icons. I'll have to check.
> From: yehoshua paul [mailto:ysp10182 -at- gmail -dot- com]
> Sent: Wednesday, October 09, 2013 12:00 PM
> To: Cardimon, Craig
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Question about "sidebars"
> One of two:
> 1. Use a note icon, which would either be a bullet or the first column in
> a table where the borders are invisible. And then enter the relevant
> 2. In online help use DHTML to create drop-down text. Users click on a
> word, and a box appears below the line with the relevant information. When
> moving the mouse over the word, the word changes to indicate that it should
> be clicked.
> Yehoshua Paul
> On Wed, Oct 9, 2013 at 6:53 PM, Cardimon, Craig <ccardimon -at- m-s-g -dot- com
> <mailto:ccardimon -at- m-s-g -dot- com>> wrote:
> 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?
> 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.
<http://www.cohodata.com/> <shawn -at- cohodata -dot- com>
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.