In option (1) it would be not advisable to name a version of your package "doc", since the documentation of the latest version of your package would have a URL conflict with the version "doc".
Option (2) is more explicit, more robust in terms of what version names for packages are admissible. However, it is longer.
Cast a vote by liking one of the posts right below this one. Feel free to discuss, as this is most likely the last opportunity to do so on this topic for a very long time.
Thank you very much! Indeed, I didn’t know. That is actually a great feature - why does Discourse hide it so well? But any case, I’m glad to be the village idiot here, as long as I can help move things forward. In the future I will definitely make a real poll!
But no, seriously, getting a sentiment from the community does help to justify the outcome of decisions that so easily trigger bikeshedding over irrelevant details. So thanks everyone for unblocking this in a very practical manner!
Can we also consider a query? E.g. https://ocaml.org/p/ocamlformat/doc/?v=latest (default to latest). Making the version of the resource part of the path itself, seems somewhat ‘un-RESTful’, if you take my meaning. A query also has the advantage that we can offer a simple drop-down to select the version (and it would just need a normal HTML form with a GET method, no JavaScript needed).
which, while technically feasible, I don’t think is very obvious. That we could navigate via a HTML form GET request is true. Nowadays, the more common way to navigate between similar pages is to render HTML links formatted by CSS.
what some doc sites do is that they assign /package/doc/... to the latest version and /package-1.2.3/doc/... to the specified version. (notice the hyphen, or we can use a dot like in opam, versus a slash which would create ambiguity)
So that would be /p/{PACKAGE_NAME}.{VERSION}/ and /p/{PACKAGE_NAME}/. Tbh, I am tempted.
However, we have a patch almost ready to land with /p/{PACKAGE_NAME}/{VERSION}/ and /p/{PACKAGE_NAME}/latest, and I think, realistically, the best way forward in terms of resources is to go ahead with that.
I interpret the current votes as the fact that people overwhelmingly prefer regularity/predictability/discoverability of the URL scheme, even at the cost of longer URLs. So I don’t think that the proposal of @hyphenrf goes in the direction of the expressed crowd preference.
The proposal, rather an observation really, is more motivated with familiarity (opam already uses the name.version notation).
The ambiguity of the slash was referencing the unpopular option of this poll.
The benefit is urls as short as what we currently have, but without the ambiguity.
I hereby announce that package documentation latest version permalink URLs are now live on ocaml.org. Package search results link to the latest version URL.
Our contributor Sayo has worked hard and learned a lot during the process as she tackled this project. Considering all the internal links, the canonical tag for the search engines and choosing the correct latest version by avoiding the avoid-version opam-flag made this a sizeable project!
Add to that that we kept making so many other changes all across ocaml.org’s templates that she had to git rebase through a lot of patches… I am happy to see how she has grown and that we got such a useful feature completed!
I wanted to check what the page would look like for Why3, and it says that the documentation failed to build: why3 latest · OCaml Package. That is fine with me, as I did not expect the server to be able to build Why3 in the first place.
What did surprise me, however, is that the corresponding error log is not the one for Why3. It is the one for Frama-C: frama-c 25.0~beta · OCaml Package. I suppose that the server tried to build both packages at once, and then got confused when it came to displaying the error log.
The documentation build process involves setting up a “package universe” (~ an opam switch that has the package and its dependencies installed). As this is an expensive step, it makes sense for the server to minimize the number of universes.
That is actually a great feature - why does Discourse hide it so well? 
But any case, I’m glad to be the village idiot here, as long as I can help move things forward. In the future I will definitely make a real poll!
Tbh, I am tempted.
