From owner-freebsd-doc@FreeBSD.ORG  Sun Jun 15 03:05:51 2003
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
Delivered-To: freebsd-doc@freebsd.org
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id F352737B401
	for <freebsd-doc@FreeBSD.org>; Sun, 15 Jun 2003 03:05:50 -0700 (PDT)
Received: from builder.freebsdmall.com (builder.freebsdmall.com
	[65.86.180.18])	by mx1.FreeBSD.org (Postfix) with ESMTP id 85B4E43FCB
	for <freebsd-doc@FreeBSD.org>; Sun, 15 Jun 2003 03:05:50 -0700 (PDT)
	(envelope-from root@builder.freebsdmall.com)
Received: by builder.freebsdmall.com (Postfix, from userid 0)
	id 2E63A1407; Sun, 15 Jun 2003 03:05:50 -0700 (PDT)
Date: Sun, 15 Jun 2003 03:05:50 -0700
From: Murray Stokely <murray@FreeBSD.org>
To: freebsd-doc@FreeBSD.org
Message-ID: <20030615100550.GA390@freebsdmall.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.4i
X-GPG-Key-ID: 1024D/0E451F7D
X-GPG-Key-Fingerprint: E2CA 411D DD44 53FD BB4B  3CB5 B4D7 10A2 0E45 1F7D
Subject: Random thoughts on indexterms..
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sun, 15 Jun 2003 10:05:54 -0000

I've recently pointed out to some people minor inconsistencies in the
indexterms, so I thought I'd do a little braindump in the hopes that
someone will add this to the FDP, come up with other guidelines, or
argue why these guidelines shouldn't be adopted.

* indexterms should be lower case unless the word refers to an acronym
  or proper noun.

* indexterms should almost never be identical to the section title.

For example
: "<indexterm><primary>backup software and basics</primary></indexterm>"

Is a bad indexterm for several reasons.  It is way too long, and not
organized properly.  "backup software" is a legitamite primary index
term, but this "and basics" reads like a section title, not like an
index entry.  The best I could do for this one was remove it since
it's in close proximity to other more succinct backup-related
indexterms.  I don't see to many secondary indexterms like "basics" or
"details" underneath a legitimate primary indexterm as I look through
the CS books within arms reach.

* tertiary indexterms are almost always bad

* indexterms should be succinct - the index must be printed in two
  column format at the back of a book.  long-winded indexterms make
  this impossible.

I don't like the :

       <primary>network card configuration</primary>
       <secondary>troubleshooting</secondary

...
       <primary>network card configuration</primary>
       <secondary>testing the card</secondary

entries in the config chapter which just mimic the section titles.
These are too long and they don't really read like index entries to
me.

That's it for now.  More later. ;)

	- Murray