Make cross-references more consistent in the docs - #6915

If you look around (e.g.: check the files you modified), an explicit id is "missing" from a lot of places, this is because, we have an implicit id by default, the sections you added an explicit id has an implicit one so they are already linkable:

• https://docs.micrometer.io/micrometer/reference/concepts/naming.html#_tag_naming
• https://docs.micrometer.io/micrometer/reference/concepts/timers.html#_pause_detection

I guess my question is: why should we do this and if it is important enough, why shouldn't we do this everywhere?

@jonatan-ivanov

By default, Asciidoctor will generate an anchor ID automatically. IMO, this is not important; it only has the advantage that when updating the documentation, a predefined ID will not be affected even if we change the title.

Yes, that's what I called implicit id above.
I'm still confused, why should we do this and if it is important enough, why shouldn't we do this everywhere?

My bad, I forgot to answer your question.

1/ About the pause-detection

The current documentation at https://docs.micrometer.io/micrometer/reference/concepts.html
does not point to pause-detection because the timers documentation does not have the pause-detection anchor ID.

We should add the pause-detection ID to avoid broken link.

2/ About tag-naming

I just think that the tag naming section should have a predefined ID. This is optional, and I can revert it.

Oh, I see the broken link now.
I found a few other inconsistencies and I think we should fix this starting from 1.14.x so I:

• rebased the PR on top of 1.14.x
• repurposed a little bit and also fixed paths in cross-references (so they are consistent and navigable from IDEs)
• fixed the anchor of "pause detection"

Thank you very much for the PR!