Docs versioning question

[crimson lion]

I saw that we have a random prefix for each markdown file created via new.sh

I'd like to understand this system more - what is its purpose? Is it for versioning?

@vast kestrel ^^

Docs versioning question

[spark quarry]

It’s to give each article a unique ID and url, regardless of its position in the structure of the docs

makes it easier to change the overall structure without ever breaking links

[crimson lion]

would it be fair to say that the overall structure could change only between different dagger versions?

[spark quarry]

Not necessarily

But that’s a common reason

another reason would be a refactoring of the docs based on new ideas on the best learning experience

or terminology changes

[crimson lion]

OK, I see

I was wondering why we used this approach instead of the one suggested in https://docusaurus.io/docs/versioning

For example, I see we are using the sidebar versioning suggested in the above link, just curious why we aren't also versioning the content the same way

[spark quarry]

It’s inspired by the tailscale docs

basically every article is a unique knowledge base entry

decoupled from narrative structure

the decoupling is the valuable part

At the time we had decided not to use docusaurus versioning for the time being, for an unrelated reason that I don’t remember . @lunar panther and @rotund siren are the best people to ask

I think those two things (docusaurus versioning and article IDs) can co exist peacefully but I don’t know for sure

[crimson lion]

So this means that when the cloak branch is merged into main, the docs for 0.2 and 0.3 will co-exist in the same folder eg. guides will contain guides for 0.2 and 0.3 together, and the 0.2 and 0.3 sidebar JS will provide the "map" as to which guide goes with each version?

Actually, I can see that main branch already does this for 0.1 and 0.2, in the sidebar JS https://github.com/dagger/dagger/blob/main/website/sidebars.js

I guess that we are also building the docs for 0.1 every time we build the docs for 0.2 as well? Probably not a major concern at this point but the process could be optimized slightly: if there are no changes being made to 0.1 docs any longer, they could be built once as a static sub-site and then removed from the regular build cadence. However this would require using the docusaurus versioning approach and plugin. TBD.

[sterile prawn]

The easiest tool so far I found which delivers versioned documentation is Antora.org, with each version pulled from a tag or branch. It requires to switch the content type to Asciidoc. Personally, I find this a better markup standard dan Markdown.

Big example of an Antora driven, versioned website: https://docs.couchbase.com/home/index.html

[crimson lion]

Somewhat dated but this is an interesting comparison of Docusaurus vs Antora: https://evaparish.com/blog/2018/10/19/antora-and-docusaurus-duke-it-out (tldr: docusaurus wins)

[sterile prawn]

I can't speak for Docusaurus, but about all of the remarks on Antora are resolved in the newest 3.0 release. A lot happens in 4 years. 😉

[lunar panther]

At the time we decided not using Docusaurus versioning to avoid breaking our current documentation urls. For instance https://docs.dagger.io/1003/get-started/ would become https://docs.dagger.io/1.0/1003/get-started/

More context here: https://github.com/dagger/dagger/pull/2066 cc @crimson lion

[crimson lion]

OK thanks

[crimson lion]

"For instance https://docs.dagger.io/1003/get-started/ would become https://docs.dagger.io/1.0/1003/get-started/" -> but wouldn't this be the correct behaviour? ie. if product v1.0 differs from v2.0, then the 1.0 get-started would presumably also differ from the 2.0 get-started. Therefore there should be a new (valid for v2.0) get-started at the original URL https://docs.dagger.io/1003/get-started/ when product v2.0 is released. The URL should not break.

(I feel like I have misunderstood something here but not sure what exactly.)

Also in the GH ticket I saw there was a proposal to have "a snapshot of docs 0.1.
Then we'll remove all 0.1 docs from our current repo to avoid confusion between the two versions.". This makes a lot of sense to me. However I couldn't understand from the ticket if this was finally implemented or not?

[lunar panther]

You're totally right, it's the correct behaviour. However, what about this URL that is only relevant for docs V1:
https://docs.dagger.io/1010/dev-cue-package/
That page doesn't make sense in Europa docs (the current one). So If we move it and get this new url https://docs.dagger.io/1.0/1010/dev-cue-package/ the previous url would throw a 404. Does it make sense ?

[lunar panther]

+1 for this one. It's a very common way to archive docs. Unfortunately it hasn't been implemented yet, apologies if the issue isn't clear enough.

[crimson lion]

Regarding the link https://docs.dagger.io/1010/dev-cue-package/ which would throw a 404: I would argue this is not really such a big issue - assuming that most people will over time migrate to the new version, this page will become less and less useful. If the page continues to see a lot of traffic and the 404 is creating issues, we can always avoid the 404 by adding a redirect to the new versioned URL.

I noticed that even with the current solution, where the link remains active, a user visiting it sees a somewhat broken site (see the screenshot sidebar).

If we use a fixed versioning scheme, then all links will always be of the form docs.dagger.io/version/slug, so even when moving the docs to a new version, old links will continue to work - therefore this seems like it would solve the problem for all future versions?

Note I'm not advocating that we should do this necessarily, just that I can definitely see some advantages to this approach.

[crimson lion]

Np, maybe we can implement this with 0.3