Re: [dita] Index in the PDF version of the spec?

["Robert D Anderson" <robander@us.ibm.com>]

> We already have a huge problem in the community with statements like "DITA
> produces crappy print output". Having the DITA governing body produce a
> print document with what appear to be bad indexing would only exacerbate
> the problem.

I don't understand the certainty that this method will produce a bad index. There seems to be a certainty that even placing *most* entries in the prolog, with exceptions as needed, will produce a bad index.

From the indexing done so far - speaking here about the more recent efforts in the architectural spec, not the old entries that need to be cleaned up / removed - if the entries we've added to the prolog take a reader directly to the title of the topic, it will be clear that they have reached the topic they wanted. For example, if you follow the index term "controlled values", there are 5 topics you can go to. Four of them have "controlled value" in the title; the fifth is about subject schemes, where "controlled value" appears in both the short description and the following paragraph.

There are clear exceptions where inline indexing will improve the result. Titled sections, as Tom mentioned and as I mentioend on the call yesterday, might be a common case. There may be others, such as definition list entries in a long <dl> of core concepts. But most of our topics now have a tight focus, where the concept we want to index is part of the title or short description, so placing those entries in the prolog seems to be the best practice.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)

<dita@lists.oasis-open.org> wrote on 07/08/2015 08:48:02:

> From: Eliot Kimber <ekimber@contrext.com>
> To: Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott"
> <scott.hudson@comtech-serv.com>, Bob Thomas <bob.thomas@tagsmiths.com>
> Cc: DITA TC <dita@lists.oasis-open.org>
> Date: 07/08/2015 08:48
> Subject: Re: [dita] Index in the PDF version of the spec?
> Sent by: <dita@lists.oasis-open.org>
>
> I don't agree with this heuristic.
>
> I hate to be difficult about this, but our audience is by and large
> technical communicators, people who have specific knowledge of and
> expectations for indexes. Thus they are likely to be the most critical
> audience possible, short of the members of the International Brotherhood
> of Professional Indexers.
>
> If the page number reference does not take you to the page where the thing
> indexed occurs they will notice and wonder why *and blame DITA for the
> failure*. Not the indexers, not the PDF generation process, not the Open
> Toolkit, DITA.
>
> That's my concern.
>
> We already have a huge problem in the community with statements like "DITA
> produces crappy print output". Having the DITA governing body produce a
> print document with what appear to be bad indexing would only exacerbate
> the problem.
>
> Cheers,
>
> E.
>
>
> ----
> Eliot Kimber, Owner
> Contrext, LLC
> http://contrext.com
>
>
>
>
> On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf of
> tom.magliery@justsystems.com> wrote:
>
> >Here's a proposed heuristic that I think might get close to everyone's
> >intuition here:
> >
> >An <indexterm> should occur inline if and only if the location to which
> >the reader is directed from the index will occur under a bolded
> >(sub)heading that is NOT the topic title. In that case the indexterm
> >should appear at the location of the nearest bolded subheading.
> >
> >I arrived at this idea after pondering Eliot's remark about users not
> >understanding/caring about incorrect page numbers. My thought is that the
> >reader will be tolerant enough to accept a jump to the nearest "title"
> >(section/topic/whatever) and scan the text from there. It's not until you
> >(the reader's) eye hits another bolded title-like item that you wonder
> >what the heck is wrong.
> >
> >mag
> >
> >
> >From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
> >Behalf Of Hudson, Scott
> >Sent: Tuesday, July 07, 2015 11:59 AM
> >To: Bob Thomas; Eliot Kimber
> >Cc: DITA TC
> >Subject: Re: [dita] Index in the PDF version of the spec?
> >
> >
> >
> >I think it is useful to provide a quality index for the specification. As
> >such, I also agree with Bob below. I think prolog indexterms should apply
> >to the entire scope of the topic, while inlines should also be used when
> >necessary. Since a lot of the spec has been broken into smaller
> >components, I also hope it is true that we should be able to stick with
> >the prolog approach in general. I do not want to rule out using the
> >inline terms, though.
> >
> >
> >
> >Thanks and best regards,
> >
> >
> >
> >Scott Hudson
> >
> >Senior Consultant
> >
> >Comtech Services Inc.
> >
> >303-232-7586
> >
> >
> >
> >
> >
> >
> >
> >
> >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas
> >Date: Tuesday, July 7, 2015 at 8:31 AM
> >To: Eliot Kimber
> >Cc: DITA TC
> >Subject: Re: [dita] Index in the PDF version of the spec?
> >
> >
> >
> >An index can be one of the better ways of finding things without having
> >to take a drink out of the firehose that is search.
> >
> >
> >I agree with Eliot's position on inline vs. prolog. The only index terms
> >in the prolog should be those that correspond with the entire scope of
> >the topic. In general (i.e., not just the spec), writing shorter tightly
> >scoped topics increases the likelihood that index terms will be in the
> >prolog rather than inline.
> >
> >
> >
> >Best Regards,
> >
> >Bob
> >
> >
> >
> >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> wrote:
> >I agree that an index is important.
> >
> >But I also feel very strongly that if the index entries are not in line,
> >the index should not be produced in PDF, for the simple reason that it
> >will result in many page number references that are wrong (because they
> >will point to the start of the topic rather than the place where the term
> >actually occurs).
> >
> >Readers will not understand or care why the page number references are
> >wrong and will assume that either we did poor job of indexing or assume
> >that DITA's normal PDF production tools can't do indexing properly,
> >neither of which is the case.
> >
> >So while having an index is important, if we can't put the index entries
> >in the source at the point of occurrence of the terms indexed then we
> >should not produce the index for PDF.
> >
> >I know from painful experience how much work it is to put index entries
> >inline if you aren't doing it as you write.
> >
> >Cheers,
> >
> >Eliot
> >----
> >Eliot Kimber, Owner
> >Contrext, LLC
> >http://contrext.com
> >
> >
> >
> >
> >On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on
> >behalf of kris@eberleinconsulting.com> wrote:
> >
> >>Background:
> >>
> >>We removed the index from the 1.2 specification because it was of
> >>extremely low quality. Since then, Robert and I have been improving the
> >>indexing as we can (placing all <indexterm> elements in the prolog),
> >>although there still are many holes.
> >>
> >>We *can* index during the forthcoming 30-day review, and I have several
> >>folks who have volunteered to work together under rigid guidelines to do
> >>so.
> >>
> >>Shall we move forward with this? I'm old school; I firmly believe that
> >>an index is an important and necessary entry point to information, and I
> >>don't think that online search can replace it.
> >>
> >>Let's talk about this. I know that we have TC members who think that an
> >>index is unprofessional in PDF output unless the <indexterm> entries are
> >>placed in-text.
> >>
> >>--
> >>Best,
> >>Kris
> >>
> >>Kristen James Eberlein
> >>Chair, OASIS DITA Technical Committee
> >>Principal consultant, Eberlein Consulting
> >>www.eberleinconsulting.com <http://www.eberleinconsulting.com>
> >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype)
> >>
> >>
> >>---------------------------------------------------------------------
> >>To unsubscribe from this mail list, you must leave the OASIS TC that
> >>generates this mail.  Follow this link to all your TCs in OASIS at:
> >>https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> >>
> >>
> >
> >
> >
> >---------------------------------------------------------------------
> >To unsubscribe from this mail list, you must leave the OASIS TC that
> >generates this mail.  Follow this link to all your TCs in OASIS at:
> >https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> >
> >
> >
> >
> >
> >
> >
> >
> >--
> >Bob Thomas
> >+1 720 201 8260
> >
> >Skype: bob.thomas.colorado
> >
> >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype
> >
> >Time zone: Mountain (GMT-7)
> >
> >
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>