Comparing Docusaurus and Starlight and why we made the switch

Absolutely any time I'm not using the latest version?

All the time. It's inevitable. If you ever sell software in the tools / configuration / package management space to "the enterprise" (which I think you do) then some of your biggest customers are going to be stuck on old versions. They'll need to easily select the version they're running if only to figure out how to upgrade to the version you want them to be running.

Edit: To clarify and drive the point home, in a previous life I was at a startup that sold something like Glasskube to enterprises. Version 3 of our software was significantly more performant and had some desirable features compared to version 2. Many of our largest paying customers literally called us up and asked us for help upgrading them. In that situation it was invaluable for our own CEO and pro services team to pull up version 2 docs side-by-side with version 3 docs, pull up a copy of the customer's code, then plan the migration for them step by step. This resulted in both revenue from the professional services and revenue from the license expansion as the customer scaled out on version 3.

So, versioned docs aren't just for customers, they're also for you, your developers (who may need to patch an old version or develop a migration tool), and your service delivery team.

I also really like sites that have site wide settings for code examples in different available languages, package managers, etc. I know this must be a maintenance burden on the teams of those projects but boy do I appreciate it as an implementer.

Having easily accessible documentation for the older versions is a must, for anything that is remotely “serious”.

Just check the Laravel docs for example, or Vue, etc…

I never want to "pinpoint changes", I want to avoid documentation totally irrelevant for the version I actually use. Here's a real world example:

Redis.io doesn't let you look up docs for any version but the latest version. The URL for docs has "latest" in the path, but swapping that for a version number just 404s. Let's look at the EXPIRE redis command and how it interacts with HSET, in the context of using Redis to cache some data with a TTL. https://redis.io/docs/latest/commands/expire/

HSET means setting a field of a hash (object/dictionary/map) to a value. EXPIRE means setting the expiration (TTL, time before autodelete) of a particular thing in redis. You can set the expiration for an entire hash in redis, but not for individual fields of that hash. HSET is like an upsert by default; it creates the hash in redis and then populates the given field with the value you set. In your application, it's pretty reasonable to want to have an operation which is like an HSET as an upsert which also sets a maximum expiration time on the parent hash, but only if there's not an expiration time set. Looking at the docs for EXPIRE, you might note that there's a special option you can set which does this exact thing, the NX flag. Thus you can implement a simple "sharded-by-hash upsert with a maximum TTL" by doing an HSET followed by an EXPIRE NX. Great!

Except that is not true! You cannot do that! Read all the paragraphs you want, you won't find this critical note unless you scroll aaaaaalll the way to the bottom of the page, past the "Differences in Redis X.Y.Z", past the Appendix, to the very last little section called "History", which isn't about the history of this page, but is instead a single bullet point of critical information noting the following:

    Starting with Redis version 7.0.0: Added options: NX, XX, GT and LT.

In such a case as this, I desperately wish that I could have clicked a little dropdown and chosen docs for Redis 6 instead of Redis 7, because this caused a serious problem as hashes just weren't expiring at all. It was especially bad because the Redis clients would send those command options to the server and the server would silently drop them, so everything looked completely fine except that the hash keys were being perpetually moved forward and never expiring!

Please version your docs!

Docs are notorious already for not being updated. Adding "versioned docs" exponentially increases the complexity, and makes updating them and reading them far harder. It's a lose/lose, for the writer and the reader.

Starlight and Docusaurus aren't much different in this aspect. Meta could decide to stop paying slorber (the main maintainer of Docusaurus) at any time. I hear from friends in Meta that Docusaurus isn't even widely used internally.

Both projects are MIT-licensed, at least, and that's a plus for continuity if someone ever wants to fork them.