RE: Pseudowriters (Should 'Pseudo-issue')

["John Locke" <mail -at- freelock -dot- com>]

Mike Stockman wrote:

> I think
> it's [missing or erroneous content) a real problem in our field.
> Even though you say "we all agree" that
> writers need to know their subject, I've contracted for over a dozen
> companies where they focused all of their energy on graphic design,
> presentation quality, search engines, and adhering carefully to
> processes, and dismissed the notion that their material need to contain
> more information, or be more accurate. In many cases, they told me that
> once the processes were in place, better content would somehow follow,
> although it never actually did.
>
> <snip>
> [H]ow have people dealt with this problem? I've actually been
> told by some managers that the writers *couldn't* understand all of the
> concepts necessary to document the product, because it was too technical,
> so the level of writing I thought we needed wasn't possible unless the
> engineers did it. Fortunately, I left shortly after that, but it would
> have been better to fix the problem than leave.
>
> Suggestions?

My approach is to ask questions. Ignore the statements that "this is too
technical for a writer," and ask a question about some extremely technical
implementation detail. If you're talking the developer's language, she's
bound to respond.

I'm in the midst of rewriting an administrator's guide for a Solaris-based
telecommunications management software suite. I've read all the existing
documentation, and another writer has put most of what already exists into a
skeleton document. I stepped away from the project and asked what does the
administrator really need to know from this document? I came up with
Installation, Configuration, and Troubleshooting. The project manager
agreed, so I've cut everything else.

Now, while reading through it, the introduction states that certain modules
can be distributed across multiple servers, but there is no documentation
describing how to do it. I got ahold of man pages from much older versions
of the software that described the individual services needed to support a
distributed deployment, drew out their interactions on a white board, and
summarized my thoughts in an e-mail to a developer. He confirmed that I
mostly had it right, but the details of interactions of the new version
weren't completely set, and he was waiting to test it out himself.

So the basic rules apply: Put yourself in your users' shoes (in this case,
UNIX administrators), and ask the simple question: what do they need to
know? With every block of content in your manuals, ask: Do they need to know
this to do the basic task? If not, you might want to put the information in
a different document, or an appendix. And always, always ask *What's missing
from this document?* As soon as you have the slightest hint, ask more until
you've nailed it down.

If you do your homework and learn the basics of what's going on, nobody can
tell you "it's too technical" because you've already proven them wrong. It
becomes a non-issue.

Cheers,
John Locke
http://www.freelock.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

          Sponsored by an
 anonymous satisfied subscriber since 1994.

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