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

["Tim Altom" <taltom -at- simplywritten -dot- com>]

This is of some interest to me, because of the amount of doc design we do.
Let's speculate on the items you bring up, Harry. This discussion isn't to
downplay the role of an index, but to see if the need for one can be
minimized.

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?

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).

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.

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

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com


----- Original Message -----
From: Harry Hager <hhager -at- dttus -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Friday, March 24, 2000 3:19 PM
Subject: Re[2]: What sayest me... on Worthless TC Degrees



>      - How do you go about discussing or mentioning the ABC window in only
>      one place in the book?
>
>      - Do you discuss the ABC window in relation to the other windows in
>      the book? If so, don't you need an index hit for these?
>
>      - How do you go about discussing or mentioning the XYZ function in
>      only one place in the book?
>
>      - Do you discuss the XYZ function in relation to the other functions
>      in the book? If so, don't you need an index hit for these?
>
>      - How do you go about cramming EVERYTHING about the ABC window in one
>      place in your book? If it's discussed in two or more places, don't
you
>      you need two or more index hits.
>
>      - How do you go about cramming EVERYTHING about the XYZ function in
>      one place in your book? If it's discussed in two or more places,
don't
>      you need two or more index hits.
>
>      - Does your book have any cross references? If yes, don't you need an
>      index hit for each occurrence .
>
>      So you don't want to help the user navigate your book? Why not
>      eliminate the TOC also. After all, if the book is well-organized, the
>      reader can look at the headers and footers to see the organization of
>      the book and to see where information is discussed. But then maybe
>      headers and footers aren't needed either because with a
well-organized
>      book, the reader will know instantly where everything is just by
>      browsing through the book. <heavy sarcasm>