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.
Subject:RE: Documenting the user interface From:Mike Starr <mike -at- writestarr -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 12 Jan 2007 11:44:09 -0500
Gordon emailed me privately and with his permission, here's my answer
and his original message.
Mike
==========
Gordon,
I'm a believer in BOTH task-based and reference documentation and I
think excluding one at the expense of the other is failing to provide
for the needs of the customer. Does this all have to be in the same
"document"? Not necessarily. I can appreciate the philosophical
approach of creating the task-based documentation as print/pdf and
making the reference documentation the essence of the online help file.
Left to my own devices, I'll put it all in both... I've got to write it
all at some point anyway, why leave it out?. I'm inclined to believe
that many, if not most, users will attempt to find the information they
need using the documentation delivery method they prefer... print or
online. If they don't find it there, they're not inclined to look in
the other documentation, even if it's available. Their next step is
typically to pick up the phone and call tech support. With my approach
they should be able to find what they need regardless of where they
look for it and thus tech support costs should be reduced. This method
requires greater investment in documentation development costs (as
opposed to the costs of development where some documentation is simply
omitted completely) and more expensive manuals but I believe it offers
greater returns in reduced support costs.
Of course, these decisions are typically not mine to make. Management
determines the approach to the documentation based on its own
philosophy, its business needs and its budget. I'm merely its servant.
Of course, I'll argue loud and long for my own beliefs but ultimately
it's my job to carry out the wishes of management. There have been many
times over the last 20 years that I've had to choke back the bile and
carry out management's ill-conceived wishes. Unfortunately, I can't
afford to be the prima donna of documentation and only do it my way. My
mortgage requires that I be a documentation prostitute rather than
being able to refuse projects because I don't want to do it their way.
I kinda diverged from your original question but that's where it took me.
BTW, seeing that you wrote me directly rather than through the list,
I'd appreciate your permission to post this response to the list as
well.
Best regards,
Mike
--
Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Website developer
Graphic Designer - Desktop Publisher - MS Office Expert
Phone: (262) 694-1028 - Tollfree: (877) 892-1028 - Fax:(262) 697-6334
Email: mike -at- writestarr -dot- com - Web: http://www.writestarr.com
----- Original Message -----
From: "Gordon McLean" <Gordon -dot- McLean -at- GrahamTechnology -dot- com>
To: "Mike Starr" <mike -at- writestarr -dot- com>
Sent: Friday, January 12, 2007 3:08 AM
Subject: RE: Documenting the user interface
Mike,
What an excellent example you gave.
Here's a thought, though, are you saying that it's 100% coverage or nothing?
That documentation that is, say 95% complete is useless? Or perhaps 90%,
80%? At what point do you need to consider your own productivity and the
business needs and constraints of the company you are working for?
Let's make the distinction here between covering every aspect of the
UI, and with a task based approach. One is exhaustive and may not
always be the most productive use of your time, the other SHOULD
cover everything in the
application. They may or may not be exclusive.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
