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.
Subject:Re: 1F8CAB asking for help From:Cees Hesp <ceeshesp -at- TIP -dot- NL> Date:Thu, 28 May 1998 13:02:40 +0200
Maybe I did not express myself clearly enough. I was not suggesting a single entry
to cover two items, but exactly the opposite.
In the original example you gave (Journal- page 45 vol I & page 234 vol II), it is left up to the reader
to find out which aspect or characteristic of journals is covered in which book. The reader either has to
look up both pages first, or has to deduce from the volume names.
In your new example+ explanation (Journal- page 45 SC & page 234 PC) you make it clear that
two aspects are being covered.
Therefore, my suggestion is to make it two index entries. For example:
- sales journal, p. 45 SC
- purchase journal, p. 234 PC
This way each (combination of primary+secondary) index entry points to exactly one "item",
where item is either a page in a book, or a topic in a help file.
Van: Sudhin U Bhobe [SMTP:sudhin -at- icodeindia -dot- soft -dot- net]
Verzonden: Thursday, May 28, 1998 12:16 AM
Aan: 'TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU'
CC: 'Cees Hesp'
Onderwerp: RE: 1F8CAB asking for help
Let us look at a situation where we have to make an entry such as
"Journals" in the index table. Now I am looking at an Accounting
Software for which I am doing the documentation. The documentation set
would obviously have a Purchase Cycle and a Sales Cycle. Journals can be
of lets say two types. Sales Journal and Purchase Journal. These would
be covered respectively in both the books. Now when a user is referring
to the Index Table and searches for the key word "Journal", I want him
to see the entry as follows:
Journal- page 45 SC & page 234 PC
where SC stands for Sales Cycle and PC stands for Purchase Cycle, which
are the titles of the two books which form the documentation set for the
and not just as a single entry like you suggest. I couldnt possibly
place sales Journal and purchase Journal together. It wouldnt make
sense. By placing the topics in their respective cycles and therefore
respective books, I will be keeping key areas more transparent to the
This is what I want to do and I am looking forward to a solution.
Sudhin U. Bhobe
Icode Software Inc.
sudhin -at- icodeindia -dot- soft -dot- net
>From: Cees Hesp [SMTP:ceeshesp -at- TIP -dot- NL]
>Sent: Thursday, May 28, 1998 2:52 AM
>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>Subject: Re: 1F8CAB asking for help
>In my book, an index that points you to multiple, different locations in 600-
>to 750-page volumes
>is never going to be much good. What happens if the index points the reader
>to 10 different locations?
>Do we really expect them to look there first, before they start calling tech
>A better solution is to provide more detailed index entries. An index entry
>should point to just *one* item.
>If it does not, then either the corresponding items have not been written
>properly (covering to many different
>aspect at once), or the appropriate keywords have not been assigned.
>At 01:00 AM 5/28/98 +0530, Sudhin U Bhobe wrote:
>>My name is Sudhin and I am writing to you from Icode Inc. I am on the
>>technical writing team. Currently at Icode we are developing mission
>>critcal business applications,. which will require extensive
>>documentation, running into a number of volumes and each volume will run
>>into atleast 600-750 pages. Our main concern is that users who refer to
>>our documentation should not miss any area and get into a situation
>>where they call us for technical support, when the explanation is very
>>much present in our documentation set. This will require us to create an
>>extensive and detailed Index, which will cover all key/critical areas.
>>I am very new to technical writing and not very conversant with certain
>>techniques.My current task is to create a common index for multiple
>>documents.I was browsing the web for a solution, when I fell upon your
>>web site. Please consider this as a personal request and help me find a
>>solution. I shall be very obliged.
>>An index entry such as 'Journal' would look as follows if we had a
>>common index for say, volume I and volume II:
>>Journal- page 45 vol I & page 234 vol II
>>I will look forward to your help in all earnestness.
>>Sudhin U. Bhobe
>>Icode Software Inc.
>>sudhin -at- icodeindia -dot- soft -dot- net