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.
Kevin observed: <<... sometimes I have a bunch of changes to do in
Word documents or in a RoboHelp WebHelp project or even FrameMaker
docs. So, I'll start. Being the sort of bloke that I am, and having
been away from a document/project for the necessary cooling-off
period, I begin to find all sorts of stuff that (wasn't part of my
initial scope for this edit/re-hash, but) just cries out for re-work.>>
There are basically three categories of such things: stuff you forgot
to do, stuff you did but want to redo, and stuff that needs to be
fixed everywhere. Do the first stuff right away; that way, if you run
out of time, you've at least made an attempt to help the user succeed
at their task. It may be ugly, but they'll still succeed. If you have
time, perfect it later during your editing pass. For the rest of it:
<<I'm saying that I can get distracted by stuff that I find and feel
the need to tweak, sometimes recursively, across many pages/topics,
at the expense of the things I initially went in to update/change.>>
This is really a matter of self-discipline: when you're writing,
write; when you're editing, edit. Anything unrelated to one of those
two primary tasks gets written down for a future pass through the
document. The simplest tracking tool is the best: your word
processor. Simply copy the topic and enough text that you can find
the specific location quickly using the search function, then paste
it into the wordpro document. Then ignore it until you have time to
come back. When you do, run through the list, one at a time, and fix
the problems.
<<So, I've been known to make two changes on a page and overlook the
other two identical items that should have been similarly changed,
because I got distracted by some other ugliness I'd perpetrated, or a
broken link, or... well...>>
Discipline, my dear boy. <g> If you can't provide it yourself, there
are professionals who do home visits, charge by the hour, take credit
cards, and will be more than happy to pay you a visit and instill
some discipline. Best of all, not all of 'em use whips or cuffs...
<gdrlh>
Just a tad less facetiously, I really am serious about self-
discipline. The best advice I ever saw for writers is that you should
not mix writing and editing: they use different parts of the brain,
and switching repeatedly between the two distracts you and makes both
tasks less efficient. When you're writing, write; when you're
editing, edit. Stop only to make reminder notes. And resist the urge
to edit anything dozens of times. This ain't literature. Work
carefully enough to get it 75% right the first time, get it 95% right
in your first edit, and get it 99% right in your final edit. (Fixing
the extra 1% would be great, but realistically...)
<<What I want is to be able to slap on a yellow sticky or equivalent
whenever I happen upon something that I should get back to, then
continue with what I was _supposed_ to be doing until that's
finished. Then I can go back and liesurely investigate the other
critters that appeared while I was turning over stones.>>
We editors have a centuries-old tool for this kind of thing: it's
called a "style sheet". Basically, it's a glorified to-do list that
you build as you work through a document, but merged with a list of
"I made the following decisions". When all the writing is done--and
only then--it's revision/editing time. Work through the style sheet
one line at a time, and in all documents in your project, search for
the specific problem and fix it. This is efficient because you get
good at making a specific correction, and each time you do it, you
get a bit faster. If you fix problems only as you spot them, you
don't get that efficiency boost that comes from repetition.
A style sheet might contain some of the following sample text (here,
but not in the actual style sheet, I've added my explanation of how
you'd do that editorial task using your software):
- Replace all "click on [button name]" with "click [button name]"
To use this one, you open each document, search for each instance of
the word "click", and delete the "on" that follows it. If you're bold
and have time for a final editorial pass, use a global search and
replace--but NEVER do that unless you're going to have time to look
for any "oops!" replacements.
- Use click, not select, choose, highlight, or press, for buttons.
To use this one, you open each document, search for each instance of
the "do not use" words, and if they are used in the context of
buttons, change the word to "click". Copy and paste means you only
have to type the replacement word once, then paste it. Great trick if
you're working with long or complex words or phrases.
- Every level 1 heading should be sentence case, not mixed caps
To use this one, you open each document, search for each instance of
the "Heading 1" style (most software lets you search for styles,
irrespective of the contents text), and check the case--then
lowercase anything except proper nouns and the first word.
- Things to do: a list of topics names, Web pages, or chapter/section
names, followed by a brief note about what you need to do there: add
a description of the Widget button, make sure that they changed the
Uggle function to work the way they described in the Nov. 26 e-mail,
replace the Snicket screenshot with the final screen, etc.
If you're working in Word, simply use the Insert-->Comment feature to
leave yourself notes. The nice thing about the comments feature (some
would say the only one) is that you can display the comments in a
separate pane. So long as you remember to check a file for comments
before finalizing it, that means you won't miss any comments because
Word shows 'em all, and keeps showing them until you delete them.
When you don't see any more to delete, you're done.
For other software, build your own comments feature: create a prefix
such as "[to-do]" or "<kevin>" that will never appear in any of your
docs, and add that at the start of all comments. Insert the comment
marker wherever you feel the urge to stop and fix something (ideally
after a paragraph), type a note that contains the necessary details,
and move on with the writing. Then train yourself to do a final pass
through all documents looking for the comment markers (use the search
function).
The simpler the comment marker (*** works really well as long as
you're not documenting wildcards <g>), the less likely you'll screw
it up in such a way that if you mistype it, you'll fail to find it
with the search function. If you're using a word, add a symbol or
pair of symbols such as *, < >, [ ], or |, so you can repeat your
search for that symbol. That way, if you type ">kkeven" instead of
">kevin", and your search for "kevin" fails, you can find the note by
searching for the >.
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
