Context-aware documentation links for Serverless

[lcawl]

Description of the problem including expected versus actual behavior:

Relates to the kbn-doc-links service, implemented in #123818

I want to be able to link from Serverless UI to appropriate Serverless docs.

However, if I add a new Serverless-specific keyword to the doc link service and update the app to use that keyword, this also affects the non-Serverless UI, as shown in #167084

I think we need a recommendation for how to code context-specific doc links consistently across our apps.

Steps to reproduce:

1. Add a new link to the kbn-doc-links service.
2. Use that new link in an app that exists in both Serverless and classic UIs.

Proposal:

It seems to me (non-developer) that we either need to: (a) provide guidance for how to update every doc link in every app such that it's context-specific (if serverless, use keyword X; if not-serverless, use keyword Y); or (b) provide a serverless-specific doc link service that contains the same set of keywords but with appropriate serverless doc targets. In the case of (b) we'd need to ensure that either the serverless- or non-serverless-specific doc link service was running, depending on the context.

[elasticmachine]

Pinging @elastic/kibana-core (Team:Core)

[lukeelmers]

Currently there are two main benefits of the docLinks service:

1. All links are consolidated in one place
2. Plugins can just use the links without worrying about any details - they will automatically be updated to reflect the right version of the stack.

So I'd be inclined to try for a solution that's closer to option b you mentioned, except maybe we don't necessarily need a separate docLinks service -- rather, we need a way to structure the list of docLinks so that we can conditionally use one or the other for a given key based on whether we're running serverless.

How this actually works behind the scenes is an implementation detail which I'll let others on the team weigh in on. Maybe we have a separate list of serverless URLs that "override" known keys on startup. Or maybe we restructure our list of URLs to have a way to store both serverless & non-serverless variants which can be picked up by the service accordingly.

What I think is important is avoiding pushing this complexity down to the individual plugin level, because otherwise we are just asking to have more unnecessary isServerless checks.

[TinaHeiligers]

I agree with Luke in that we shouldn't push complexity down to the plugin level. Thinking along the same lines as option (b) sounds like a better solution than creating a new service to pretty much do the same thing as the existing one and because Kibana can only run in one environment: either it's serverless or not.

One thing I'm not sure about is if the doclinks become static after Kibana's built. If they are, then perhaps using the environment for which we build Kibana's an option?

[pgayvallet]

So I'd be inclined to try for a solution that's closer to option b you mentioned, except maybe we don't necessarily need a separate docLinks service -- rather, we need a way to structure the list of docLinks so that we can conditionally use one or the other for a given key based on whether we're running serverless.

I agree. I think we could fairly easily adapt the docLink service and the underlying getDocLinks method from @kbn/doc-links to accept an additional serverless boolean option.

kibana/packages/kbn-doc-links/src/get_doc_links.ts

Lines 13 to 18 in fe22ff0

	export interface GetDocLinkOptions {
	kibanaBranch: string;
	}
	export const getDocLinks = ({ kibanaBranch }: GetDocLinkOptions): DocLinks => {
	const meta = getDocLinksMeta({ kibanaBranch });

That way, we could just change the urls of existing link depending on the environment (serverless or not).

E.g instead of this line:

kibana/packages/kbn-doc-links/src/get_doc_links.ts

Line 43 in fe22ff0

settings: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/settings.html`,

We could have

settings: isServerless ? SERVERLESS_SETTINGS_URL : TRADITIONAL_SETTINGS_URL,

Regarding adding new doc link entries that would be specific to serverless (not used in traditional), I would simply add them to the DocLinks interface and return them in both environment, given they would just not be used on traditional (I can assume this is already what we already do in the opposite situation today, as we're probably exposing traditional-only links on DocLinks that are not used on serverless). So having our DocLinks interface having urls used exclusively on one of the other env doesn't seem like a problem to me.

Overall, keeping a single interface and a single implementation seems the best for everyone (consumers don't need to change anything, and also easiest maintaining the docLinks provider ihmo).

There's a minor detail of sending this "isServerless" flag to the UI within core service, given the docLinks service is instantiated both on browser and server, and the "isServerless" info is, AFAIK, not directly sent to the browser atm, but that doesn't sound like anything that could be a problem.

If we're all fine with the idea, and if it's already a pain point for the doc team, I can probably take a shot at implementing it next week or so.

[dedemorton]

What is the status on this effort?

[pgayvallet]

I apologize, the lack of replies caused the issue to not surface back in my notifications 😅, so it never got prioritized. I'll take the thumbs up as a go, and I'll start working on this asap.

[lcawl]

Thanks @pgayvallet ! As soon as support for this type of condition is added, I'm happy to take the work of updating all the existing links in the list. If there's anything else I can do to help, just lmk!

[pgayvallet]

I just opened #172358 for review. I'll notify on this issue once merged

[florent-leborgne]

Hey @pgayvallet. Not sure if we have a lot of these cases yet, but I'm wondering if we could consider pushing the "context awareness" to solution types for serverless?

I think in the docs there are (or will be) features where:

• we have 1 shared doc for all solution types (i.e. only need 1 link for stateful + 1 link for serverless)
• we have 1 doc for each solution type (i.e. 1 link for stateful + 1 link for Obs serverless + 1 link for Sec serverless + 1 link for ES3 serverless, and no 'serverless generic' link).

cc @lcawl

[lcawl]

Hey @pgayvallet. Not sure if we have a lot of these cases yet, but I'm wondering if we could consider pushing the "context awareness" to solution types for serverless?

It looks like at this moment, the "build flavours" are traditional and serverless per

kibana/packages/kbn-config/src/types.ts

Line 31 in 47614ec

export type BuildFlavor = 'serverless' | 'traditional';

, so those are the two we can distinguish between for now.

My hope is that the places where we're calling solution-specific doc links are also solution-specific UIs and thus can use unique keywords in the doc link service. If we can find examples of where that's not the case (i.e. the same code is re-used in multiple solutions and thus needs some way to be context-aware with the doc links it uses), that would be useful for figuring out how to address them.