XREFs in Short Descriptions

[antonyterrence]

Hi Team,
This topic says that xrefs are not directly allowed in shortdesc.
https://www.oxygenxml.com/dita/stylegui ... tdesc.html
However, as per DITA 1.3, xref is allowed in shortdesc.
Is that article still relevant?

[Radu]

Hi Antony,

The DITA Style Guide is written by Tony Self and is a slightly older publication, in the meantime the DITA standard went through various changes, I added an issue on the DITA Style Guide Github project: https://github.com/hyperwrite/DITAStyleGuide/issues/7
We are actually attempting to re-publish the DITA Style Guide on our web site as WebHelp Responsive output integrated with our new WebHelp feedback forms which should make it easier to give feedback directly on topics.
About using links in shortdescs, in my opinion this is not such a great idea, a short description may also be used as a tooltip and tooltips are plain text, what do you present in a tooltip when there are links involved?

Regards,
Radu

[antonyterrence]

Thank you. We are not recommending xrefs in short descriptions. I was doing research because of the build errors we see when we publish topics that contain xrefs in short descriptions. We were trying to identify the cause of build errors given that the DITA spec allows it. That's the context of this question. As a best practice, we still ask our writers not to use xrefs in short descriptions (for the reasons you specified and the OASIS article on Writing Effective Short Descriptions).

[Radu]

Hi Antony,
I cannot reproduce on my side those build errors when shortdesc contains an xref, I'm testing with the DITA OT bundled with Oxygen 24.1, a small DITA map published to HTML5.
Regards,
Radu

[antonyterrence]

I need to check with my colleague. I think there are build errors when using DITA OT 2.5.