Feedback [LONG]: right vs. complete?

Subject: Feedback [LONG]: right vs. complete?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 15 Jul 2003 12:37:07 -0400


John Posada wonders: <<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?>>

As a useful starting point for thinking about this problem, consider that
information could be categorized into the following broad categories:

- Information that must be completely accurate or someone could get hurt or
suffer significant losses (monetary or otherwise). This information must be
sufficiently complete and accurate that nobody suffers from errors or
incompleteness.

- Information that must be sufficiently complete and accurate that most
readers will solve their problems with minimal or some effort, and
relatively few users will fail. This information must be "good
enough"--sufficiently complete and accurate to meet the user's needs, even
if it's not fully complete and accurate.

- Useful but not crucial information: This can be somewhat inaccurate and
incomplete without harming anyone because they don't need the information.
Of course, someone somewhere sometime will need the information, so the fact
that it's not crucial to _everyone_ doesn't mean you should be sloppy about
it.

Since we rarely have time to do everything, it pays to concentrate on
triage:
- Make the essential information as complete and accurate as humanly
possible.
- Next, work on the "can survive with difficulty if the information isn't
fully complete or accurate" by concentrating on identifying the most
important areas where incompleteness or inaccuracy would cause significant
problems. Work on those areas first.
- Fix everything else as time permits.

It's no coincidence that this sounds a lot like minimalism (as defined by
Carroll and van der Meij and their various followers).

<<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.>>

Obviously, you'll need to do basic QA yourself (reading the documentation
against the current interface)--as is the case in any documentation
project--but you'll also have to get the SMEs involved in reviewing the
information. They're the experts, after all. Unfortunately:

<<I'm... 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)>>

Sympathies. But the important thing is that the developers are willing to
work with you on this. Talk to them to find out how you can minimize their
workload for reviews (e.g., do they prefer online vs. on-paper vs.
interview-style reviews; do they want to review few large chunks in a single
sitting or many small chunks in several sessions). This will increase the
amount of cooperation and the turnaround times.

<<...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 typical if the managers don't want to document things (as noted
above) and the developers working under these managers must tiptoe through
the political minefield. If they have no reason to answer you, why would
they do that and risk missing their own deadlines? As always, you'll have to
find a way of working directly with the reviewers and motivating them to
help. Do you have any other allies who can help with the reviews? (Try the
technical support, quality assurance, sales and marketing, training, etc.
departments.)

<<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... 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.>>

Not necessarily a good assumption. If upper management doesn't know or care
about the documentation process (commonly the case), then they won't bother
evaluating how their junior managers respond to your requests. Worse yet, if
there's no carrot or stick for those junior managers to respond, they won't:
they have nothing to motivate them to respond, and nothing to fear if they
don't respond. So why would they respond?

<<if it's wrong, they had every opportunity to get it reviewed and if they
don't care, should I?>>

Yes, you should care. It's unlikely that anyone's going to die because most
of the docs we create are inaccurate, but there's always a risk of that
most-serious consequence or of less-serious but still nasty consequences.
More selfishly, even if you are not responsible for errors, you're still
going to be the one blamed for them. Surely you don't think a junior manager
will step up and accept responsibility? You might be cleared of any
responsibility in a court of law, but in the court of corporate opinion...

<<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 it reviewed.>>

The problem with this approach is that you end up being seen as
passive-aggressive: if the senior managers do spot a problem and come down
hard on the junior managers ("why didn't you respond to John's e-mail?"),
you know you're the one who will be blamed, or at least resented. That will
undermine your working relationship with the junior managers, exacerbating
and prolonging your current problems.

There's no easy solution. If there's no corporate culture of responsibility
and quality assurance, then you can't create one yourself. Getting senior
managers on your side is the best way to proceed, but may be impossible; you
generally won't have a chance to shape their opinion, and neither will your
manager (though managers have a better chance of working higher up the
chain). If you can't start shifting things towards a culture in which
reviews are considered important, make sure that you get your boss' approval
for your current approach in writing (not e-mail). You said that your boss
approves, and that's great, but if the fecal matter hits the rotary
impeller...

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.



Previous by Author: Nielsen frags PDF with misinformative Alertbox... AGAIN!
Next by Author: Work-for-hire question?
Previous by Thread: Re: SDLC and work flows
Next by Thread: dynamic forms


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


Sponsored Ads