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

Clarify need for link attributes in docs

    XMLWordPrintable

Details

    • False
    • False

    Description

      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.

      Attachments

        Issue Links

          Activity

            People

              broldan@redhat.com Robert Roldan
              gmorling@redhat.com Gunnar Morling
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: