introduce documentation registry ids to avoid breaking links

[samuelstroschein]

Problem

Documentation links are at a high risk of breaking because they have no ID.

Any change in the slug will lead to breaking links. The reasonability that redirects are in place is not given. This requirement came up in https://github.com/opral/monorepo/issues/2205. The issue proposes linking to the docs from Paraglide JS compiled code. Even if the latest version of Paraglide JS always has up-to-date links, old versions of Paraglide JS will contain broken links to docs.

-inlang.com/documentation/concept/message
+inlang.com/documentation/concept/messages

Changing a slug for SEO purposes, comprehension, or any other reason leads to breaking links.

Proposal

Have a documentation registry similar to our marketplace registry to avoid breaking links.

Example

1. The example below uses j2s as id for the message concept docs.

inlang.com/documentation/j2s/concept/message

2. Someone renames the slug.

-inlang.com/documentation/j2s/message
+inlang.com/documentation/j2s/concept/message

3. The renaming will not lead to breaking links because j2s is used to resolve the correct document.

Additional information

• I propose changing inlang.com/documentation/* to inlang.com/docs/{id}/* for easier to read links alongside this issue. This issue requires redirects for all exists docs links already. Why not shorten the path along with it?

• The ids can be considerably shorter than marketplace registry IDs. I propose starting with 3 characters. 36 (letters + numbers) x 36 x 36 yields 46656 possible IDs, more than enough for docs.

[samuelstroschein]

@NilsJacobsen as always, close if you disagree.

[NilsJacobsen]

I see the problem with paraglide js linking and linking in general, but I feel like the id concept works best in one-level hierarchy routes like marketplace products (see amazon). Until now we didn't do a large amount of renaming in the docs without redirects.

I would wait until we actually run into the problem.

haha why is there no link versioning :D

• give me inlang.com@1/documentation/message
• or inlang.com@2/documentation/concept/message

That could fix the internet :D

[samuelstroschein]

but I feel like the id concept works best in one-level hierarchy routes like marketplace products

Docs are one level. Everything is one level. There is no need for nesting except for "human organization". This is the same insight why namespaces are not important. There is still a hierarchy in my proposal but the hierarchy only exists for human peace of mind, not to resolve docs.

inlang.com/docs/{id}/{hierarchy}/{hierarchy}
inlang.com/docs/2js/concept/project

I would wait until we actually run into the problem.

Hmm. Rest assured, that will happen, and you will get 404s in ahrefs. We are coding docs links now into paraglide js & co. If those links break, the UX will be bad. There is no way to know if a link breaks in testing, which makes this even more problematic.

Are you sure that this is not worth it now?

[NilsJacobsen]

Hmm, well, I think that will have value. I think I also pushed back because it is a quality benefit and doesn't bring us growth or adoption right now. I would keep it open so I can take over after the communication and docs part is mostly done. Then I can push the quality topic.