The use and display of shortdesc

[mbakeranalecta]

Currently few topics in documentation set have a shortdesc element. I counted 39 instances, but several of those are empty.

In some cases, the use (and display) if shortdesc is causing redundancy. For instance, in the windows install topic the display of the shortdesc means we end up introducing the procedure three times:

Windows Installation
Windows installation procedure.

The following steps describe the installation procedure of Oxygen XML Developer, valid for Windows:

We need to be consistent about how we use and how we display the shortdesc.

[raducoravu]

I agree that when the short description provides about the same information as the title, it is redundant and could probably be removed.
The short description appears both in the actual topic HTML content and under each related link at the end of a topic. We also have plans that in the WebHelp output when you hover the TOC to present as a tooltip the short description for each hovered topic reference.

[mbakeranalecta]

I think part of the problem is that currently there are many topics that are really just building blocks. They are not written to stand alone but to flow from the parent topic. They contain no introductory text because their context is established by their relationship to their parent.

Since the shortdesc is designed to hold introductory context-setting text, there is really no role for it to play in these building block topics. Nor should such topics really be the target of links, because they do not set their own context.

I think we need to make a clear distinction between topics that we consider to be "presentation level topics" -- units to be presented to the reader, and building block topics that are scaled principally for reuse. The former should have shortdesc. The latter probably should not.