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.
> 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...)
Well, it's rare that I get to sit and write for extended
periods. I'm not in the position of stepping into a new
company with a new product that's never been documented.
What mode is one in when doing updates? For me, it's
both.
One thing that happened recently was that a Sales Engineer
was working with a prospect in an industry we had not
previously addressed. He was using existing hardware and
software and docs to set up a demo, and the customers
were having a hard time with one of the features and
the concepts around it. So he had an "aha!" moment
and wrote up some explanation and a "test case" that
was more to the potential customer's liking.
When the Sales Eng showed it to me, I liked it, too and set
about incorporating his version into my WebHelp. As I added and
revised, here and there, I began to see other places where
similar re-thinking was going to be useful, where sample
input/output in syntax pages should be altered, where
the rationale for some housekeeping tasks could be better
presented, such that it made sense with the other new/adjusted
material... oh, and some new terms in the index and glossary.
Oh, and I thought of something to ask the Engineering Test crew
about this.... and oh, this reminds me of something else that
I should Eng Test.... quick, write those down... uh, what was
the first one again...?
Perhaps a voice-activated recorder around my neck?
> <<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.
That's fine if the problem is a word, a spelling, a punctuation
usage, a format.
> 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.
[...]
> 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.
In theory, yes.
In practice, those aren't usually the types of things I'm
revising. It might be that our technical support people
have pointed out that a way of explaining or referring to a
concept is troublesome for some customers, or that the
explanations or examples (that possibly were useful two
years ago) are outdated or need a new slant for a whole new
crop of customers in a different industry.
> - Every level 1 heading should be sentence case, not mixed caps
Again, if it was a change to headings, it would more likely
be a re-think of what _should_ be "level x" or "level y",
or a brilliant change of phrasing... that now should be
propagated to a dozen other pages in the Help... and doesn't
this suggest a pattern for pages in general... but I'd have
to add this kind of heading where I don't have it on several
of this kind of page, followed, in many cases, by some text
to fulfill that function... hmm... where was I again?
> 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.
Ah, well, it's the "aha" moments when deciding what should
be on that list... or added to it... or tracked down to
decide whether... it's those that are distracting.
Also, while I'm busily writing down (or copying and pasting)
to give myself sufficient landmarks to:
a) recognize the place I need to return to, later
b) remember what it was I want to modify there,
I can easily forget the other idea or two that popped
into my brain.
The point of the yellow-sticky approach was that it be
quick, that the place-marking be either automatic (put
the meta-marker wherever the cursor happens to be when
the hot-key combo is pressed, or pop up a yellow sticky
and attach it wherever it gets dragged), and I just
start writing what I want to say/do, given that the
way-pointing has been done automagically. The key is
that it should be minimally intrusive on the thinking
process - that it should not displace a thought or idea
or concept with housekeeping details. Maybe it should
also have hinting, if a new sticky starts looking like
a previous one... there I go dreaming in Technicolor again.
> 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.
There's that, yes.
My wish was for something that wouldn't leave overt footie-prints
in Word or Frame or RH documents. That is, I'm trying to get away
from multiple strategies to comply with multiple tools.
> 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).
I once imported a strategy like that "<fix me!> into Help, where
(just to add to the confusion) every second page had text in angle
brackets. Then I took the longest contiguous vacation I've ever
enjoyed, came back, read somebody else's doc where they'd used
<fixme>... and started inserting <fixme>s into my own stuff...
guess what I overlooked when somebody came around with a rush request.
:-)
Have you heard that old saw that says you make something "yours"
by doing it consistently for twenty-one days?
Somewhere, I have a collection of DayTimers, DayRunners - brand
name and various other similar "systems", most in lovely
leather covers - with one, two, even three months of nice
little entries, following whatever system was preached to
go along with the paper-and-leather.
I've never lasted with those things. They give me headaches.
My To-do list is on a white-board behind me.
I rarely call meetings, but I get to other people's meetings
because they include me on the invitee list (I don't even have
to ask anymore) and Outlook reminds me when to go.
What I'm saying is that what works brilliantly for some people
is counter-productive for others.
My old manager (whom I still work with as closely as ever,
in contrast with my nominal manager who's in another country)
writes up comprehensive minutes after meetings. Then she
brings 'em to the next meeting and scribbles notes and action
items all over them, which then become the new minutes and actions.
Another manager in this office tried it that way and ...
couldn't decipher his own writing when he got back to his desk.
He went back to thumb-typing every note and action on his PDA.
That wouldn't work for the woman in the previous para because
she needs to see the "underlay" for her own scribbles to make
sense to her.
K
The information contained in this electronic mail transmission may be privileged and confidential, and therefore, protected from disclosure. If you have received this communication in error, please notify us immediately by replying to this message and deleting it from your computer without copying or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
