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.
Re: Documenting Floating windows - how would you do it?
Subject:Re: Documenting Floating windows - how would you do it? From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Fri, 23 May 1997 08:47:44 -0500
>
>Carla,
>
>First of all, IMHO, the documentation should not be organized by module, but
>rather BY TASK. Task-oriented documentation is generally much more useful
>than module- (or function-) oriented documentation. It is my experience that
>users do not need to know about "modules". They are more concerned about
>tasks that they are trying to accomplish using the software. And if the doc.
>is organized by task, then there are no such things as "floating windows"!!
>
>Second, I am in favor of repetition for the sake of clarity. So, if several
>tasks require the user to work with a specific window, then repeat the
>description of that window in each task that uses it.
>
>Fabien
>
I suggest a hybrid between a task-oriented and a modular approach. That
is, the logistic flow is task-oriented (no turn the page to this section
and then turn back) but the mechanics of the document design is modular
(only one written section for each common window/function).
To clarify this apparent paradox, I suggest encasing the common blocks
of documentation in bookmarks. The common areas could be the first
incident of the floating window in the documentation. As an alternative,
the common information could exist in a separate document that serves as
a library but is not actually part of the produced/printed document.
Instead it is an information server. Therefore, the procedures, intros,
examples are presented in a task-oriented approach. When a point is
reached in the task where the floating window information is required,
insert a link to the applicable bookmark in the server/library document
module (bookmark for the initial incident).
Using bookmarked-text allows updates to occur at only one location.
Therefore, the tasks which include the common information update
automatically. This is much less time consuming and consistent than
updating "umpteen" incidents of the common information. It also does
not impact translation as much as multiple repetitions. This is because
only the original (bookmarked text) is translated. The references are
links and will update to show the translation.
Mike Wing
>
INTERGRAPH
| Michael Wing
| & Principal Technical Writer
| Infrastructure Technical Information Development
| Intergraph Corporation; Huntsville, Alabama
| : http://www.ingr.com/iss/products/mapping/
| ( (205) 730-7250
| . mjwing -at- ingr -dot- com
>
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
