backstage: [RFC] TechDocs URL Inconsistency problem - Each docs page has two URLs

Coming back to this almost 7 months since originally posted…

With all of the composability work that’s gone into Backstage as a whole, and TechDocs in particular… Is this perhaps no longer really a decision for us as Plugin Developers, and more a decision for each individual App Integrator?

One organization may go all-in on the Catalog and customizing the entity page, including embedded docs. Another organization may choose to forego the docs tab on an entity page, instead only showing them under, e.g. a /docs folder. Yet another could choose to do both!

For us, it’s just a matter of ensuring it’s possible to have more or less the same experience using one or the other. …That may involve a little more work to expose some of the things @emmaindal mentioned (e.g. extra metadata in the header) as composable building blocks. …And also perhaps some documentation work to advise on the pros/cons of each approach (or mixing them).

What do y’all think?

Yeah, this will become a bigger issue when there is an interface for searching things… Presumably, a documentation site/page should only have a single result, but if so, how do we know where to point them?

To that end, I like your proposal @OrkoHunter, but perhaps with a tweak or two. Lemme know what you think:

• There should be a way to indicate when a docs site is “documentation only” or attached to a service/other entity. If it’s “docs only,” then its canonical URL is at /docs, and if it’s tied to an entity, it’s under /catalog. Redirects work the same way as you outlined above, in any event.

I find this confusing for APIs too. My brain doesn’t grok why I have to go to a separate page to search for APIs. I thought the idea of Backstage was to have a single catalog to hang functionality off.

(This is a rethorical comment 😀)

In terms of user experience I think our developers would want go to the service entity for technical documentation (and api docs as dtuite said) about a service and go to the documentation page (/docs) for documentation which isn’t related to a service e.g. golden paths.

Whatever solution is agreed upon, I think it’s important that it respects that this is two different use cases / scenarios.

Taking @OrkoHunter 's original proposal up in his description, I might pitch a slight nuance based on the thread here. (specifically changing the “redirection” point)

Updated proposal:

• There should be one and only one URL when a user is looking at any docs page.
• They could have been redirected from somewhere else and that is fine.
• Keep the /docs page a.k.a. the TechDocs homepage where users can browse documentation sites and all other available service documentation.
• Keep the /catalog way of browsing documentation.
• Redirection
  • When documentation is attached to an entity, redirect the /docs way URLs to /catalog way.
  • When an entity IS documentation, redirect the /catalog way to the /docs way.

In this way, either link “works” - and they should all be visible on the techdocs homepage. But clicking my service documentation jumps me to my component entity page in the catalog, showing my service and starting on the docs tab immediately. While clicking on my independent golden path instruction documentation, keeps me in the pink techdocs theme at /docs route and shows me the docs there. In some ways, it begins to lean in to elevating a kind:component + type:documentation up to a 1st level kind:documentation.

Is that sort of where we’ve headed?

There is a related discussion going on in #2791. You can skip to https://github.com/backstage/backstage/pull/2791#issuecomment-719974174 for the more relevant bits.

My reasoning is the difference is the purpose of the documentation. Since backstage is built around entities it makes sense to be able to get the documentation for those entities where you go to view the entity. A pure documentation entity could be anything. Something like Coding guidelines and best practices that doesn’t have a logical connection to a service or other entity type.

Regarding the documentation entities showing up in the service catalog i think that makes sense in a lot of cases since quite often they’ll have a CI/CD pipeline etc. Currently they’re only shown if you specifically select the Documentation filter in backstage though so they won’t show up by accident when looking for other things.

Edit: I don’t think there’s anything stopping us from linking to the /docs url when clicking the Docs tab on a documentation entity if we don’t want the confusion of having several urls for the same doc page.