Make documentation available via/in Backstage

[marians]

User story

• As a Giant Swarm platform user, I want to access documentation in the developer portal provided by Giant Swarm.

This issue is mainly for gathering ideas.

Ideas

TechDocs

Backstage provides the TechDocs function to make some documentation available directly in Backstage. The most common use case for TechDocs is to provide access to docs for a specific software component. The documentation source resides within the component code repository (docs folder typically).

As of now (Dec 2024) only few Giant Swarm components provide TechDocs (i.e. docs folder in the repo). Should we move more documentation into the repos? What to do with content that resides in docs.giantswarm.io exclusively, should this be duplicated? (technically difficult, as we use Hugo in docs but don't use Hugo in TechDocs).

Linking to docs.giantswarm.io

We can (and should) simply link to documentation at docs.giantswarm.io. We may introduce a special link format / icon for this, or do this in some other particular way so that users recognize the special sort of link.

The most difficult parts here are (1) adding all the relevant links and (2) maintaining them. This requires some sort of process.

APIs

APIs have a special place in Backstage. Our CRD documentation might be covered by APIs at some point. There is a separate issue for that.

[marians]

• Martin: Backstage could potentially help find docs for certain topics.
• Maybe Backstage search could also integrate docs articles.

In general, docs linking should be part of other feature stories/specs.