[platform-help-dev] Re: What info will be returned on search hit lists?

["Mary K Maguire" <maguirem@xxxxxxxxxx>]

Dorian wrote:

>>For HTML documents, <title> is a good candidate, but when the help
documents are XML files (appropriately styled), this won't work, unless we
treat each document type differently.<<

If authoring in DITA XML; DocBook; etc., <title> is the appropriate
candidate for labelling search hits. I would be surprised to find a
topic-based DTD that did not use <title> to name the topic.

>>how difficult is it to author documents and navigation so that topic
labels match the titles, and have them short enough to avoid TOC
cluttering, but also long enough to be meaningful by themselves, with the
parent context?<<

When authoring in XML, the <title> tag typically becomes the navigation
entry for the topic (either by extracting <title> from the topics at build
time and writing them to the Eclipse navigation XML file, or by
transforming an external navigation map into Eclipse navigation XML). In
either case, the assumption is that <title> is what appears as the
navigation entry. There may, however, be cases where we want to shorten the
<title> text for presentation in the nav, in which case we would likely use
some kind of <shorttitle> tag in the topic source or navigation map. Given
this possible mismatch between topic title and nav label, I would agree
with Leigh that it's much better to display search hits based on the full
<title> of the topic.

I would also suggest that we introduce (at some point) the ability to
extract a <shortdesc> from the topic and display it in the search hit list
(as opposed to displaying the first few lines of text). In the case where a
<shortdesc> is not available, you could fall back on displaying the first
few lines of text, similar to the method you suggest for titles (that is,
displaying <title> if it's available and falling back on nav label
otherwise).

In answer to Konrad's question, displaying the first few lines of text is
certainly valuable if that's the only option. If the topics are authored
correctly, the first sentence should provide good context.

Hoping I haven't completely missed the point...

Mary Maguire
ID Team Lead - WAS Enterprise Edition
maguirem@xxxxxxxxxx
Phone: 415-545-4530, T/L: 473-4530