indexing software manuals

[Ned Bedinger <qwa -at- HARDY -dot- U -dot- WASHINGTON -dot- EDU>]

Greetings to the techwr list readers.

I came across this discussion (included at the end of this post)
in the gis (geographic info systems) newsgroup, and thought it would be an
appropriate place to begin a discussion of indexing strategies-- a sore
subject for some of us who have to create printed indexes for material
that is provided in print as well as hypertext.

Indexing is a sore subject (at least to my mind) because there is
less time allocated now to indexing. Publishers of software
documentation are providing on-line help using keyword searching, and
paying less attention to traditional methods of providing access to
information.

Now, I am not attempting to foment some recidivistic neo-Luddite move-
ment away from technology and innovation.  I feel very positive about
the benefits of electronic indexing.  I do, however, feel like there
are some real problems with modern publishing and the de-emphasis of
printed documentation, especially indexes.  I think of indexes as an
opportunity to structure information.  I think that indexes should be
done by people who understand indexing and the need for word lists. I
think that indexes are increasingly being treated as an afterthought, as
if they are a quaint and anachronistic, even optional, distant cousin
of the table of contents.

The student in the included discussion brings up a really interesting
point, echoed recently by a programmer I was interviewing when he opined
that "We are in the business of software, not documentation."  Pity the
user who has to work with documentation motivated by THAT!

_______________________________________________________________________
Begin excerpt:
_______________________________________________________________________
llins -at- KEAN -dot- UCS -dot- MUN -dot- CA> said:
>Boy oh boy. We students at GEOIDAL (Geographical Information and Digital
>Analysis Laboratory, Memorial University of Newfoundland) have
>become rather annoyed with SPANS. We really think that those who wrote
>the software should NOT write the user manuals. For example, on the
>subject of importing points, the manual begins its instruction by
>saying "..this function is the SECOND step in converting an ASCII
>file...". Correct me if I'm wrong, but shouldn't you start on the
>first step? Nowhere in the 'import' chapter does it say how to
>accomplish the first step. It took much searching before finding how
>to use the PNTBA routine. Why can't software manual writers create a
>complete index for students? After all, we'll be the ones in the near
>future who recommend what software to buy. It seams to us that the
>manuals are written assuming that you already know the software, and
>the accompanying literature is just a reminder.

>Any thoughts?

>Mike, Memorial University
>P.S. We like Spans OS2, but the manual sucks.

Amen to that!

The poor students in our Intro to GIS class bought the tutorial manual
(and tutorial disks) for Atlas*GIS.  The tutorial was great and
contained a wealth of information, but there was NO index whatsoever!
It was like hunting for a needle in a haystack.  Talk about
frustrating the students.

Like Mike says, it's today's students who will recommend the GIS
package for tomorrow.  Hopefully the writers will realize that soon.

--------------------

Karla K. Streharsky                  Bitnet:   strehar -at- akronvm
The University of Akron              Internet: strehar -at- vm1 -dot- cc -dot- uakron -dot- edu


_________________________________________________________________________


I hope that some of you find indexing to be a compelling avenue of
inquiry.  There are lots of unresolved issues regarding the indexing
of software manuals, especially programming language manuals, that are
being skirted as we move toward electronic indexes.  Let's kick it
around, eh?


qwa -at- u -dot- washington -dot- edu