Uploaded image for project: 'Debezium'
  1. Debezium
  2. DBZ-4776

Clarify need for link attributes in docs


    • Icon: Task Task
    • Resolution: Done
    • Icon: Major Major
    • 1.9.0.Beta1
    • None
    • documentation
    • None
    • False
    • False

      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)?

      broldan@redhat.com expressed concerns about the downstream docs tooling not being able to properly handle anchor-only links.

            broldan@redhat.com Robert Roldan
            gunnar.morling Gunnar Morling
            0 Vote for this issue
            4 Start watching this issue