Command documentation structure

[madolson]

It's come up several times if we want to version our APIs. My preference is that if we can get away without it being too confusing I would rather only have a single version of the docs for each command with all the command history listed. I have used a lot of different applications with per-version documentation, and I generally find it to be more confusing than helpful. But, I would like to get feedback from other folks.

The second point is I think the structure of the commands should be:

https://valkey.io/docs/commands/<component>/<version>/<name>
e.g.
https://valkey.io/docs/commands/valkey/latest/command-name

I know this is super verbose, but it then makes it easier to clarify if something is part of the core, part of some other module (maybe we'll host additional modules that aren't strictly valkey or our distribution), and then make it clear it's the latest so if we switch to versioning later it will still work.

[zuiderkwast]

Agree we don't want versioned docs. The history entry we have is enough and very good. I also wouldn't like long complex URLs. It's nice to be able to type an URL in the address bar like how you type in a terminal. So https://valkey.io/commands/xreadgroup etc. is my preference. Also aligning with existing links in the content in the doc repo is important. Let's not change for the sake of changing.

[PingXie]

The ultimate rationale for API versions is to provide guarantees on compatibility. The API version is essentially the major version of the project IMO. I don't see any value in creating another version just for the APIs.

[madolson]

You're probably right, I might be over thinking it.

[daniel-house]

This is why I like docs embedded in the source code, managed in the same repository, and vended directly from the server.