RE: Image/screen capture annotations for documentation

Subject: RE: Image/screen capture annotations for documentation
From: "David Artman" <david -at- davidartman -dot- com>
To: shawn -at- cohodata -dot- com, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 23 Jul 2014 09:57:51 -0700

I see a few things to address:

* Tools - Inkscape. Free. Saves to SVG, if you insist (I save to PNG as
the SVG is overkill and can be hard to work with in some environments).
Or GIMP. Free. Saves to PNG.

* Callouts - Use alphabet for item callouts, numbers for sequence
callouts. Follow with a table of definitions or the procedure step
enumeration. Makes localization MUCH simpler, and you don't care
anymore if the callouts in the image are searchable (they won't be if
you save to PNG, as I do).

* Sizing - You'll probably have to make callout 'templates' (layers
ready to duplicate to your working images) at two or three sizes, to
scale with the screens properly (e.g., one set for 96-dpi, as-is
screens; one for 150-dpi, just-a-bit-too-large-for-the-margins screens;
one for 300-dpi, full-screen-at-1280x1024 images). Or scale the screen
in your art application before importing the callout layers, which
shouldn't scale upon duplication and thus should all be the same size
in your DTP environment.

* Style - There's an infinity of ways to do them, usually driven by one
or more of the following:

-- Legal fonts use

-- Marketing/business colors/typography

-- Contrast with background screen or photo (usually means at least two
style standards for callouts, or use of drop-shadow or halo other
contrast-enforcing effects on the callouts)

-- Lines, arrows, boxes; rounds, effects; rounded-rectangles,
circles/ovals, line-curves, line-angles (if there's a Draw object
setting, you need to have a style rule for it, even if just to make
your callout 'templates'!)

-- Color-blindness accessibility (e.g., you can't safely use red as
"wrong" and green as "right" without additional shape clues)

-- Localization, but usually only an issue for sequential callouts.
English alphabet item callouts can be left untranslated because they're
fundamentally just 'shapes' that allow you to provide a legend/key
(i.e., imagine if they were all dingbats: you'd still be able to
correlate the shape to the table of definitions, right?).

* Multiple deliverables - Here's where I start to get stumped or go in
circles. PDF output is easy: I know my dpis and margins. HTML should be
easy: I can drive the dpis and sizing with code, when I don't just
leave them unscaled (no height/width/scalefit/etc attributes) and let
the rendering browser scale them to fit. But when I want precise size
control AND it's going to an unknown browser to render (e.g., a phone v
a tablet v a laptop)... I'm stumped as to what to do with that. Sure,
can play with scale attribute and float and such-like, or gimmicks like
scaling with a zoom option (i.e., thumbnailing). But the actual art
file... What does one do with it? Leave always at 96 dpi, possibly
making a much larger download than will ever render (e.g., a
full-screen screen capture rendering on a phone!)? Pre-shrink the image
(downsample) to save size but then lose details that could be seen when
the user tries to zoom in?

And how about photos, which inherently are freakin' huge and must be
downsampled, scaled, sized, etc before any callouts are even considered
(e.g., part assembly instruction)? Downsample to 300 or 600 dpi after
sizing to a 'happy medium' for all potential rendering devices?
Downsample but don't resize, let the renderer size them to fit their
bounding box on the devices, but leave users downloading huge files
(which are, at least, very zoomable)? Deliver a set of downsampled and
resized images every time and use server-side code to push the right
one based on browser ID (HUGE labor in the art application, unless well
automated with macros or similar; and fragile on the code end, unless
browser ID has gotten better than when I last messed with it)?

Sorry to piggyback on your more-basic thread, but there's really a LOT
to consider in the subject of annotations, in our modern multi-channel

Hope this helps; and I hope someone can help me get my head around
preparing artwork--on a budget! ideally single-source!--for
multi-channel output.


Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Previous by Author: RE: Terminology Question
Next by Author: RE: _"Infographics_â_A_Special_Mode_of_Technical_Commun ication"
Previous by Thread: RE: Image/screen capture annotations for documentation
Next by Thread: Re: Image/screen capture annotations for documentation

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

Sponsored Ads