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.
My question first, since this is a long post and you may not have the time
or inclination to read to the end:
Is it better to include substantial content that's mostly right and mostly
useful but unreviewed, or is it better to include substantially less content
that is known to be 100% right?
Background: Had a conversation with my boss yesterday. I told him that I'm
currently in the process of going through an 800mb collection of existing
documentation for content and details to be included into my documentation.
I'm using it to fill in alot of background information and to compare
against my current content to highlight possible differences.
He asked how I verify that all the information that I do use is accurate
since most of it is 2 years or more old. BTW...this collection of
documentation is supposed to be kept updated by the system's management and
development staff..it's not an archive, but a working collection.
Understand that I'm at a branch office under the mandate of the HQ CTO,
documenting a system that while I'm getting some cooperation from the
developers, the management of that system doesn't want documented (its a
political thing...don't ask) and the developers are reticent to devote any
more time than they can get away with. Therefore, while they've agreed to
give me minimum access, are not jumping through hoops.
My response, which many of you aren't going to like, was the following:
Up until recently, I worked every day to get content reviewed. I would
either write or rewrite/update a piece, then present to management for
dissemination to the appropriate staff for review. The problem was that I
would get no response, not even an ack of the email.
That's when I decided a new approach. Now, I'll write new content or rewrite
existing content when I know the facts for certain. I will then offer to
submit it for review and if the offer goes unheeded, it goes into the
documentation unreviewed (this is internal documentation). On a regular
basis, I post the documentation to an internal web site and let a group of 7
department managers know of the update..2 from that system and 5 managers
from HQ to who the 2 report.
Here's the tricky part. I assume that if a manager of the system being
documented cares about how their system is represented to the company's
upper management, they'll take a peek at what's being written about it.
However, if I get no comment, I assume that either I'm correct, or they
don't care. If it's the former, then great...I'm getting it right. OTOH, if
it's wrong, they had every opportunity to get it reviewed and if they don't
care, should I?
I was asked what if upper management finds something wrong in it. I replied
that I WANT it found...by the higher the person, the better. Then, when I'm
asked why it went in, I point to where it came from (the source was the
system itself), and I have the many unanswered emails to show I tried to get
BTW...my boss agreed with the approach.
Senior Technical Writer
NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3
Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-
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 http://www.raycomm.com/techwhirl/ for more resources and info.