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.
This is perhaps the greatest problem I have seen in writing documentation.
It sounds like the software in question was not designed with the end user
in mind. When that happens, no amount of documentation can make a bad
design, or the bad implementation of a design, better than it is. And very
often, the people who create this problem blame us when our writing
illuminates the problems they created.
Good documentation cannot fix a bad design or a bad implementation.
What you can do is write functional documentation rather than task
documentation and let the user worry about how to organize the tasks using
the software. This way you won't be making obvious the software's
unsuitable implementation.
Tom Murrell
Senior Technical Writer, Alliance Data Systems
"There is no magic in the world. Some poor S.O.B. has to code everything."
----------
>From: Anthony Markatos <tonymar -at- HOTMAIL -dot- COM>
>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>Subject: Task Oriented Documentation For Non-Task-Oriented Software
>Date: Sat, Aug 28, 1999, 12:59 PM
>
> Question to all listserv members:
>
> In creating end user documentation for an existing (complex) software
> package, if the software was NOT designed task oriented, can the end user
> manual be written in such a fashion?
>
> Typically, to accomplish a given end user task with our software, you have
> to travers up-and-down through several (seemingly totally unrelated)
menus.
>
> Problem: When you write task oriented documentation for this sofware
(i.e.
> bring all required menu selections together under the specific task), the
> lack of task oriented design becomes glaringly evident. The documentation
> acutally prompts the end user to ask the question "Why do I have to do so
> much jumping around between menus to accomplish a given task?" This does
> not make us look good.
>
> All responses appreciated.
>
> Tony Markatos
> (tonymar -at- hotmail -dot- com)
>
>
> ______________________________________________________
> Get Your Private, Free Email at http://www.hotmail.com
>
>
