Best Practices (was Re: Summarizing Edits) (also was: Document Review Techniques)

Subject: Best Practices (was Re: Summarizing Edits) (also was: Document Review Techniques)
From: doc -at- edwordsmith -dot- com
To: techwr-l -at- lists -dot- techwr-l -dot- com, ekarenski-techwrl -at- yahoo -dot- com
Date: Thu, 22 Dec 2005 17:09:52 -0800

Too bad about the subject line, perhaps it will appear in finer mail clients
as part of one of the techwr-l threads I am replying to....

I've been mulling my response to the Edit question, and had all but forgotten
it in my drafts folder until the Reviews topic reminded me of it. I've been
mulling my response to the Reviews question and had all but forgotten about
it when the Doc Plan question reared up, reminding me that I often reply but
only (apparently) as a form of mulling.

Not wanting to face up to the likelihood that techwr-l life is passing me by,
I am happy to report that I've synthesized a fused response that covers what
I wanted to say about each (Edit and Reviews). I respctfully submit my
comments late/absurdly late. Please see below.

On Monday 05 December 2005 12:47, Karen wrote:

> I've created a form with the following subsections:
> Punctuation
> Numbers
> Consistency
> Grammar
> Word Choice
> Would anyone care to share their approach?

I go for a 'levels of edit' approach, where the items you've listed are copy
edits. While I haven't had a copy editor (or any editor) on the
documentation team for several years, I still tend to push this work off
until the last, focusing instead on content, or substantive edits as it
were. I track changes, but I don't use intrinsic word processor features like
change tracking because of the congential problems that M SWord has evinced
when tracking changes in documents that have auto-updating fields.

Tracking changes is most important during review cycles, because the document
is putatively frozen and ALL changes are notable. So, when I get review
comments back, I start tracking by cut-n-pasting each and every one (even the
redundant comments) into a separate document, adding the page/line number of
the change and the contributor's name and the date--this document becomes my
plan for updating the reviewed document.

The tracking continues as I make each reviewer's changes in the actual
document. For each change, I add the changed text to the plan, so it now
shows the original comment AND the comment as it is incorporated in reviewed
document's context. I also add the page/line number to the plan make it easy
to find in the change in the reviewed/revised document.

When I've finished all changes, I send a copy of the plan (now more of a
change log) back to the reviewers so they can see what other reviewers had to
say (and not incidentally to give them the streamlined opportunity to verify
that I understood and executed their changes).

I'm sure that many tech writers and some managers will think that my change
tracking methodology is just so much noodling and that it adds unnecessary
overhead to a project. In defense of my approach, I think that it
facilitates reviews by promoting them as an interactive exchange, which in
turn approximates a roundtable approach without the overhead of having to get
everyone together and ready to review at the same time. I think the change
log that I send back to the reviewers is appreciated for, among other things,
providing a very usable alternative to the awkward revised document with
tracked changes.

Ned Bedinger
Ed Wordsmith Technical Communications
"Better absurdly late than never."


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release.

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

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

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

Summarizing Edits: From: Karen

Previous by Author: Re: not an artifact, just a document
Next by Author: Re: Documentation review
Previous by Thread: Summarizing edits?
Next by Thread: RE: Summarizing Edits

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

Sponsored Ads

Sponsored Ads