Introduce stable way to link from products to documentation

[nikku]

Describe the Problem

We link from our products from many places to the documentation, to establish "additional context". This is helpful for our users, and we must ensure that such links don't break unnecessarily.

In the past we've relied on product-links.txt and redirects, however such mechanism is brittle, as it does not allow to detect and redirect anchors, that break, too. A more robust mechanism is needed, I think.

Product links as a mechanism requires continued maintainance, and future content/docs structures may conflict with past, now redirected pages.

Proposed Solution

I propose that we don't directly link into the documentation anymore, but host dedicated knowledge base short links as part of the documentation. These are targets from our apps, and can freely re-direct to respective content in the documentation, including (changing) anchors, etc.

Desktop Modeler Links to stable place -> [DOCS]/kb/12jsadsa1.html
[DOCS]/kb/12jsadsa1.html -> resolves (redirects) to actual URL, i.e. [DOCS]/abc/foo#abc today and [DOCS]/abc/foo#asdsads in the future.

Alternatives

• We could create static deep link pages, in the individual component sections.
• We could stop linking to local anchors, so product-links.txt mechanism continues to work (with its limitations)

---

Related to conversation
Related to https://github.com/camunda/developer-experience/issues/67

[christinaausley]

@pepopowitz @camunda/tech-writers Can I get your thoughts on this? Happy to tackle this when I'm back from FTO in September.

[pepopowitz]

I'm definitely willing to try this! The product-links approach has never seemed like the perfect approach, so any iteration to make it better sounds good to me.

[mesellings]

This is a great idea, using some kind of GUID that resolves to the docs would be good - not sure if "kb" is the right path term to use though? Could we just have the GUID straight after the docs link, e.g. [DOCS]/GUID.html?

Anecdotally, this is always then the preferred way to externally promote links to everybody, so that they bookmark the GUID link instead of the actual page, BUT in practice this is very challenging, and a real behaviour challenge across users/internally, as people will typically just bookmark the page they are on, by which time they are on the redirected page 🤷 .

[akeller]

@pepopowitz would this close out #3433 as not planned?

[pepopowitz]

@pepopowitz would this close out #3433 as not planned?

No, I see this as a separate issue. This issue is specific to product links; 3433 is general to all links using anchors.

[pepopowitz]

My thoughts on implementation for this:

• We add a section of rules to the .htaccess file, clearly marked with a comment that the section is for links from the product.
• The rules in that section use temporary redirects, not permanent, in case we want to change the target over time.
• We start with a subset of links, as an experiment. @nikku can you put together a set of links that you'd like to see handled in this experiment?
• If we find this experimental approach to be helpful, we add any remaining links later.

The only open question, I think, is finding a URL scheme that everyone is happy with. I don't have strong feelings about what the URL scheme should be. I appreciate that the /kb/ in a URL means it will not conflict with any actual docs pages, and identifies it as a vanity URL; I also appreciate that not having /kb/ makes it a little more human-readable. If anyone has very strong opinions about this URL scheme, they should propose their scheme as the path forward. Otherwise, I would leave it up to the discretion of the person implementing this change in the docs.