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

Clarify need for link attributes in docs

XMLWordPrintable

    • 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
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

              Created:
              Updated:
              Resolved: