This follows up on
DBZ-4606. There I commented along the following lines:
Reading our documentation writing guide, I'm wondering now whether we need to have the link alias attributes in docs. That's what it says on cross references:
Note the following advantages of the xref: macro:
- You do not need to specify or know the location of the file where the custom-connector ID is defined. AsciiDoc automatically figures this out at build time.
- Consequently, if you move files around, you will not break any links.
In that light, why do we bother with all the link aliases at all, instead of solely referencing to the anchor ids? Or is it that the downstream docs build actually does not live up to what's described above (in which case this documentation guide needs updating)?
firstname.lastname@example.org expressed concerns about the downstream docs tooling not being able to properly handle anchor-only links.