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.
Offline I'm receiving comments like "Ronni, I couldn't agree with you
more!" "I'm working on a similar project right now!"
While online the responses are very different!
To Alexia and Wayne who say...
> good docs will uncover flawed designs.
I say, you're absolutely right -- good docs reveal flawed designs.
However, the reality is that when you're the doc manager of a
hardware/software company and the president says: "Here's the product,
this is the deadline, get it out the door on schedule or you'll be out
the door!!" and the programmers say, "It works as designed!" or "We'll
fix that in the next rev!" flawed designs or not, you've gotta document
it to make it look as good as possible.
Does that happen frequently? Damn right...a whole lot more than most
of us would like to admit. Profits margins, deadlines for trade shows,
OEM contracts, the volatility of the industry -- there are lots of
reasons why products go out the door flawed or "before their time."
Wayne says...
> If the installation procedure sucks, your manual will map it exactly.
True.
> And it will look like the kludge that it is.
Not necessarily. You can break down a complex install into smaller
chunks...or explain things to users along the way to keep them on
track... There are lots of things you can do to make a less-than-perfect
product look better. No, that's not fixing the problem, but I'm not a
programmer/engineer. I'm a doc writer/editor/manager, and I see my job
as making things better/easier for users, even if it means documenting
less than perfect products.
Alexia says:
> as Wayne pointed out, never underestimate your users. Fatal mistake.
Is making a program appear to be less flawed than it is
underestimating your users. No, I don't think so!
I maintain a file of reviews of the products I've done docs for, to show
to prospective clients and headhunters. To cite a couple of examples...
* For a system which I documented a while back, "PC Magazine"
wrote: "Its outstanding documentation makes the initial stages of
setup and learning much smoother than they would be with most other
systems."
* For a peripheral I recently worked on, the review states that the
card did things well -- and "with class" -- thanks in part to the
"helpful documentation."
It's not an ideal world out there. There's a whole lot of
less-than-perfect hardware and software on the market. I may not be able
to fix the product, but I can create documentation that makes the
product look less awful than it really is.
So returning to Wayne's original comment...
> You can't write a manual that's better than the product.
I still think you can...and I've got the reviews to substantiate it! ;-)
