Changes To Documentation URI

[rgajason]

Hello all,

I've noticed multiple changes to the documentation URI over the past couple weeks. I wanted to share my experience with those changes. To level set:

• Originally, no version / branch in docs URI
• For a short time, specific version and main were the options
• Currently, specific version and dev are the options
• There does not appear to be forwarding from any of the old formats to the current (there does appear to be a "latest" URI that redirects but isn't otherwise selectable)

Issues I'm experiencing:

Broken Search Engine Results

Many search engine results (Google/DDG) still point at the original URI scheme

Cannot Quickly Grab Long-Lasting Links

I used to be able to just copy/paste the contents of my browser's URL bar into my own docs / code comments to reference the Starlite docs. Now, the URI is version-specific by default, so I have to first change to dev (previously main) before copy/paste or manually change pasted content to other desired URI.

My preference would be that the site always defaults to latest or main (or even dev) and that the URI reflect that default. If someone wanted a specific version they could then change to that version using the nice dropdown that has been added.

Just my $0.02 - I appreciate the work being done to this project. The community has been very helpful. The frequent changes have been well worth the benefits they bring in bug fixing, feature addition, and general improvements.

Thank you!

[provinzkraut]

I apologise for the hiccups, the transition process could have been smoother. But the issues should have all been addressed by now.

There does not appear to be forwarding from any of the old formats to the current

There is. You can go to e.g. https://starlite-api.github.io/starlite/usage/0-the-starlite-app/ and it will redirect you to https://starlite-api.github.io/starlite/1.48/usage/0-the-starlite-app/.

Cannot Quickly Grab Long-Lasting Links

You can. Just use a versioned link like https://starlite-api.github.io/starlite/1.48/. Those will (hopefully) never change. The latest and dev ones are not guaranteed to be permanent, which is expected and kinda by design. latest will always just be a redirect to whatever the latest version is, and dev will always just point at the version deployed from main, i.e. the development branch.

This is in line with pretty much every other versioned documentation I know, where by default, you link to a specific version, if you want permalinks, and not latest.

My preference would be that the site always defaults to latest

It does. Visiting https://starlite-api.github.io/starlite/ is the same as visiting https://starlite-api.github.io/starlite/latest, which in turn will redirect you to the latest version, e.g. https://starlite-api.github.io/starlite/1.48.

and that the URI reflect that default.

It does if you're using the dev branch (which you probably shouldn't, since you don't want to use a non-released version in production)

If someone wanted a specific version they could then change to that version using the nice dropdown that has been added.

I somewhat disagree with this. I think the docs defaulting to the latest released version is fine. And having latest not a selectable version is fine as well, since it would create confusion. If you have e.g. latest, dev and 1.48, you'd think they're three different versions, but they're not. latest would just be an alias for the latest release, in this case 1.48.