A structured way to link related docs across reference/concept/troubleshooting

[florent-leborgne]

Basically, a related articles feature.

Solving which problem?

Because we're splitting the various content types, we're starting to see notes like this more and more as it's still quite important to link pages that are about the same topic together, regardless of their content type.

In terms of UX, this isn't great to start a page with such notes, even less at scale, and it's not ideal either to write the links plainly as normal text, because it navigates to a different doc set, with a different navigation, etc, equalling to switching context.

It may be nice to think of a way to automate those cross-set links in a way that standardizes the wording and display, with the ability to give it a rendering that is not disturbing the reading.

Logic idea

Maybe some logic that leverages the frontmatter like:

• associated_ref: kibana:://docs/reference/therefpage.md
• associated_concept: docs-content://explore-analyze/thepage.md

Then when building the page, have something automated: if parent == reference && "associated_concept" is not empty --> "This page includes reference information about $$title. For conceptual information and more details on its usage, refer to $$associated_concept."

Possible benefits:

• we can choose and standardize the wording
• we can choose and standardize the display of such information (and maybe not have to use very colored admonitions at the start of many pages) in a way that is more helpful and less disturbing with some nice design.

[leemthompo]

Big ++. It would be a huge win if related docs were linked in a standardized manner:

• Helps users always know how to parse a page for important links or find the right page if they're not on it— because they're always formatted identically
  • Reduces jarring inconsistencies
• Helps writers by reducing the cognitive overhead of asking "How should I call out this link or flag a potentially important reader redirect"

We could of course start by aligning as much as possible in meantime.