Re: Documentation Sanity Check

Subject: Re: Documentation Sanity Check
From: "Kat Nagel, MasterWork Consulting" <mlists -at- masterworkconsulting -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 8 Apr 2003 17:48:30 -0400

At 4:56 PM -0400 4/8/03, John Posada wrote:

How many of you take the data from your documentation,
massage it in a different application than what it was authored in, and if you do, what have you found?

You ask...why in a different application? I guess for the same reason that an author is the worst person to copyedit his own work. By putting in a different application, you get a different perspective that the original docs could not give you.

Do you periodically check existing content when not initiated by a change in the subject being written about?

At least once per review cycle for most of my print projects. For about half of my freelance projects over the last 15 years, and all but two of my projects for the so-called 'permanent' position I had for 15 months, the deliverables had to as WinWord documents. Since I rarely was given the time or budget to produce decent documentation in Word and still make a profit, I usually did the actual work in Frame on my Mac and converted the final draft (or each review draft if I had the luxury of a review) to Word for proofing just before I handed it over.

Going that direction, I found a few factual errors I hadn't caught earlier, a bunch of formatting gotchas like wrong heading levels, and *lots* of things I wish I had phrased better.

I've had to go the opposite direction a few time for freelance projects---write a document in Word for a client that doesn't do Frame, and then convert the final Word draft to Frame for my client to deliver to his client. I discovered far more errors that way: scrambled sentences, wrong captions, and many formatting problems. But whether these were actual errors in the original doc or problems with Frame's less-than-stellar RTF conversion, I can't say. I never had time to go back and compare, just to fix the thing and move on. (I wouldn't do it that way any more; I would use a product like mif2go, which wasn't available then.)

I've considered using a similar technique for web site projects. I do most of my html work in BBEdit, and check the resulting pages in several browsers on both Mac OS and Windows. But I still get reports of 'broken' pages when they are viewed with certain validators or with browser versions I didn't specifically test. Most of these problems seem to be due to missing/unpaired tags or extra spaces. I'm thinking about viewing the html code in another editor that uses different conventions for displaying tags and other elements in the source document. Seems to me that would be useful for catching that type of error--sort of like proofing a print doc in hardcopy as well as on the screen.

Another item for my 14-page to do list.

Kat Nagel
Owner, MasterWork Consulting Services
Phone: (585) 820-4045 Fax: (585) 244-3565
Business: katnagel -at- masterworkconsulting -dot- com
Personal: katnagel -at- bluefrognet -dot- net

Purchase RoboHelp X3 in April and receive a $100 mail-in rebate, plus FREE RoboScreenCapture and WebHelp Merge Module. Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Documentation Sanity Check: From: John Posada

Previous by Author: RE: Principles for proceedure writing
Next by Author: Re: Creative Technical Writing (LONG reply)
Previous by Thread: Documentation Sanity Check
Next by Thread: RE: Documentation Sanity Check

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

Sponsored Ads