Temp/permanent annotations?

Subject: Temp/permanent annotations?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 25 Nov 2006 08:18:38 -0500

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 >.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart ghart -at- videotron -dot- ca

(try geoffhart -at- mac -dot- com if you don't get a reply)


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

Previous by Author: Laptops: travel insurance? Summary.
Next by Author: Paragraph numbering?
Previous by Thread: RE: Temp/permanent annotations?
Next by Thread: RE: Temp/permanent annotations?

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

Sponsored Ads