Re[4]: What sayest me... on Worthless TC Degrees

Subject: Re[4]: What sayest me... on Worthless TC Degrees
From: Harry Hager <hhager -at- dttus -dot- com>
To: techwr-l -at- lists -dot- raycomm -dot- com, taltom -at- simplywritten -dot- com
Date: 27 Mar 2000 07:51:35 -0600


>This discussion isn't to downplay the role of an index, but to see if
the need for one can be minimized.<

Why would you want to minimize the need for an index (except for
budgeting reasons as you mention at the end of your message)? An index
is one of the primary navigation tools a reader has for the book.

>First, there is the issue of the multiple references to the ABC
window. If the writer had an appendix for all relevant windows, with
all reference data there, wouldn't that keep the user from having to
look up those items in the index?<

For user manuals, I place a screen shot of the window when the task
accomplished by that window is discussed. Time permitting, I have also
used an appendix for all windows. But, as far as I can remember, I
have never removed the windows from where they are discussed in the
text and placed them only in an appendix. I don't understand how this
would help the reader.

>When you say "XYZ function", I assume you mean a task for the user to
perform, not a function in its technical sense, as it might be in an
API manual. In that case, why wouldn't a manual structured as
task-based satisfy that need? In the Clustar Method, for example, we
break down tasks into clusters and prominently label them as such. For
instance, the XYZ function might be "Executing the XYZ Function". This
cluster could then be placed in a logical position in the doc, with
cross-references extending to other clusters that might need them
(something that's easy in Frame, by the way).<

Yes, function = task. Yes, I use a task-oriented structure for my user
manuals. Yes, I group similar tasks.

No, this doesn't change the need for indexing the various windows.
Unless you have a very simple piece of software, the multiple windows
are very inter-related. Let's say a user is in window ABC and selects
to perform task DEF and as a result the program opens window DEF. On
the other hand, if the user selects to perform task GHI from window
ABC, the program opens window GHI. So on and so forth. The
availability of this kind of switching windows to perform various
tasks probably happens numerous times in numerous windows.

Therefore, when I discuss window ABC at this point in the text, I will
have an index hit for window ABC, task DEF, window DEF, task GHI, and
window GHI, and any other window and task to which the user can switch
to from window ABC.

>Cross-references, properly done, wouldn't need index entries. For
example, cross-references from "Executing the XYZ Function" could
mention the QRS function, the 897 function, and the THX function.
Properly planned, such "print hypertext links" could make sure that
the user had alternate paths supplied without flipping to the back.
And those cross-references can become literal hypertext links if you
output to PDF, HTML, XML or the like. The document itself becomes a
conceptual web.<

Perhaps my meaning for a cross reference wasn't clear or correct. What
I mean is that when I do use cross references, as you indicated in
your examples, I will have in the text all the words needed to make a
complete cross reference. However, everything that is cross-referenced
will also get an index hit. That way the user can, if they choose to,
find not only the main discussion of the task (window, function,
whatever), but also the event(s) that enabled the user to get to that
task (window, function ,etc.).

>Given that most manuals don't get indexes due to budget constraints,
perhaps such a strong structure would make a reasonable substitute.<

One does what one needs to do. It's too bad if an index cannot be done
because of budget constraints, but it happens.

H. Jim Hager
hhager -at- dttus -dot- com


Previous by Author: Re[2]: What sayest me... on Worthless TC Degrees
Next by Author: Re: In Search of a Class
Previous by Thread: Re: What sayest me... on Worthless TC Degrees
Next by Thread: Re: Re[4]: What sayest me... on Worthless TC Degrees

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

Sponsored Ads

Sponsored Ads