RE: Documenting the user interface

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.

Gordon

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

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

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Previous by Author: Re: Documenting the user interface
Next by Author: Re: Documenting the user interface
Previous by Thread: Re:Documenting the user interface
Next by Thread: RE: Documenting the user interface


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


Sponsored Ads