lelandbatey 4 days ago

I want versioned docs literally always. I am basically never on the _most_ recent version of a software package, so being able to pick the version of the docs that matches my actual version is genuinely not negotiable.

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.
Redis 8 released this month, Redis 7.0.0 released in April 2022. Some version of Redis prior to 7 (6.4) will be explicitly supported by Redis the company till August of this year. I encountered this particular hiccup much further back when it was very reasonable to still be using Redis 6.X

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!

1
antirez 3 days ago

As the person that wrote such documentation, I respectfully disagree, I understand you point but I want to tell you why I believe the way it is, is better for Redis. Redis is a system that is 99% backward compatible across all versions combinations: Redis 2 was released more than 10 years ago, and this is a very hard to find case where things are not perfectly backward compatible, but still in a case where the Redis 2 semantic was so odd to be avoided in most tasks. Now, in a system like that, to have man pages that tell you the differences among versions is much better than versioned documents where you would require to diff yourself among the different pages. In a single document you know all the behavioral history of a particular command, that often is just: "always as it used to be", plus features that are backward compatible entering newer versions.

lelandbatey 3 days ago

I think a changelog on the page is key, as you say. I also think that having versioned docs does not requires us as users to do diffs manually, that's what a changelog/history is for. Ideally, I'd like to have both: all docs are versioned and all docs have "history" sections.