Documentation Sanity Check

Subject: Documentation Sanity Check
From: John Posada <JPosada -at- book -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 8 Apr 2003 16:56:06 -0400

lately, I've become fixated on having all vital data in my documentation
cataloged by visual (flowchart/diagrams), or in Excel tables. The nice
thing about having all vital data represented in tables is that you can
create different views of the data for different parts of the documentation
based on how you extract the data.

So, over the last 2-3 days, I've been going back through all my Framemaker
tables and reimporting the data into an Excel table, then sorting, grouping,

What I found was that a substantial amount of data is either transposed,
obsolete, missing, applied incorrectly, or not applied uniformly across the
documentation. I can understand HOW it happens, you're rushed, you're giving
erroneous information, you make stupid errors, names change in the
application being written about but you either don't know, aren't told,
don't realize the significance until too late.

While this is bad in my eyes, it seems that what would be worse is to never
check and not know about it in the first place. question. 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?

John Posada
Senior Technical Writer
jposada -at- book -dot- com
icq: 178047452
aim: jposada1
"When you only have two minutes to do
something that takes three, wait until you have three"

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.


Previous by Author: RE: Principles for proceedure writing
Next by Author: RE: shortsighted or realistic?
Previous by Thread: Re: Teacher---Andrew hurt my feelings! (longish)
Next by Thread: Re: Documentation Sanity Check

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

Sponsored Ads