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:How evil is copy-and-paste? From:Geoff Hart <geoffhart -at- mac -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 19 May 2005 16:09:45 -0400
Craig Hadden reports: <<Recently I updated a user guide in which the
original author thought it was a really smart idea to use
copy-and-paste to duplicate a _lot_ of content (instead of using
cross-references, would you believe).>>
Depending on the length of the material, this can be a very good
strategy. Cross-references are wonderful for what they do, but what
they do isn't always pretty: they take the reader out of the present
task (reading one thing or following a procedure) and force them to
interrupt that task to do another thing (flip through the book or
follow a trail of hyperlinks).
As a rule of thumb, with up-front acknowledgment that this is a very
subjective call, it's better to repeat material when it's relatively
short (a few sentences or numbered steps) and better to cross-reference
with more difficult or complex procedures. Another decision criterion
might be that you should cross-reference when the topic is only related
to the topic and is "only" useful to know rather than being an
essential part of the current topic. If you can't complete the
procedure without flipping pages or following a link, a cross-reference
probably isn't the best choice.
Arguably, a well-designed single-sourcing solution would entirely
eliminate the cross-references and embed the key content in each
procedure where it appears, possibly as an optional link or secondary
window for online stuff or as a sidebar for printed material. That
eliminates a major annoyance: interrupting the procedure to go
elsewhere for information.
<<Then today I read a 10-sentence software change-request in which
literally _half_ of the sentences each began with the same 21 words!
("The amount of any Deduction processed through payroll with a Type X
should be added to the figure in the...")>>
This suggest the need for either a bulleted list or a heading: the
repeated information becomes the introductory sentence or heading that
provides context for all the following sentences. The general
principle: Why repeat something 5 times when you can repeat it once,
just as effectively?
<<I'm beginning to think of various rules of thumb about
copy-and-paste, such as: * Paste no more than 3 words at a time.>>
See above re. headings and bulleted lists where the information appears
very close together. But this particular guideline can be a problem if
certain phrases are essential, and will be repeated many times in a
document but not in proximity. For example, what about a phrase such as
"Open the Format menu, select Styles, then..."? For some types of
document, you might need to repeat this dozens of times. In others, it
would be more effective to cross-reference to the page or topic on
Styles:
<<* If you paste the same item more than, say, twice, think again about
what you're doing.>>
This one makes considerable sense. If you understand what you're trying
to accomplish and why, you can decide whether the text should be
repeated or cross-referenced.
<<As Geoff Hart put it so eloquently, "the thing to remember about
"rules of thumb" is that thumbs bend when necessary".>>
I'd forgotten this one, but in hindsight, it's one of those rare
phrases that I enjoy as much now as I did when I coined it (if indeed I
wasn't paraphrasing someone else... "there's nothing new under the
sun", as they say).
New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
