(cross-ref) online OCaml manual: there should be an easy way to get a fixed-version URL

[gasche]

This is a cross-reference to an issue with the OCaml manual which I posted upstream at

https://github.com/ocaml/ocaml/issues/11458

Suppose I'm browsing a random page of the OCaml manual

https://v2.ocaml.org/manual/types.html#sss:typexpr-sharp-types

and I want to refer other people to it. The URL above I found through my search engine does not mention a specific OCaml version, so it is not stable, it may be dead or contain different content next time we look at it.

Feature wish: it should be easy to get a fixed-version equivalent of the same URL, just like github offers an interface to get a "permalink" from the source view of a versioned file.

There is a version name in the top-left corner of the page that says "Version 4.14". I would expect that clicking on it brings me exactly to such a fixed-version version of the page, but in fact it brings to https://ocaml.org/releases/ which is certainly not what I'm looking for.

Note: this would be easier if the URL scheme was regular among "current versions" and "fixed version" manual pages. Currently we have:

• https://v2.ocaml.org/manual/attributes.html
• https://v2.ocaml.org/releases/4.12/manual/attributes.html

so there is no way to guess the fixed-version URL from the current-version URL. Instead we could have

• https://v2.ocaml.org/releases/latest/manual/attributes.html
• https://v2.ocaml.org/releases/4.12/manual/attributes.html

where I could easily guess that replacing "latest" by a version number will give me what I want.

[dbuenzli]

Instead we could have

• https://v2.ocaml.org/releases/latest/manual/attributes.html
• https://v2.ocaml.org/releases/4.12/manual/attributes.html

That's not even good. Here's a user interface you will remember without effort (and these v2 should go #465):

• https://ocaml.org/manual -- HTTP 303 --> https://ocaml.org/manual/latest
• https://ocaml.org/manual/latest
• https://ocaml.org/manual/$(VERSION)

After all these years of efforts on the ocaml website that's something simple and obvious we could expect.

[gasche]

Actually grepping through the ocaml.org sources, it looks like a "latest" schema is already supported

https://github.com/ocaml/ocaml.org/blob/0b9086770d29b45fc8a1dc69dcc580330ba83ecd/src/ocamlorg_frontend/url.ml#L22-L26

(but weirdly enough the "latest" and "with_version" URLs have different structure)

The problem is that the search engine has indexed URLs with another structure ("ocaml manual" gets me to https://v2.ocaml.org/manual/index.html), and there is no redirection towards a more canonical URL, and no way to find through through the page content itself.

[gasche]

After all these years of efforts on the ocaml website that's something simple and obvious we could expect.

Aha, years of effort on the compilers as well and many "obvious" (... once you are told about them) usability things are missing.

[dbuenzli]

Well tracking manuals and release notes (which became even worse in this incarnation of the website) is an old age issue https://github.com/ocaml/v2.ocaml.org/issues/1128. If you start something over it's usually good to have a look at past issues.

[sabine]

Here's a user interface you will remember without effort (and these v2 should go #465):

* https://ocaml.org/manual -- HTTP 303 --> https://ocaml.org/manual/latest
* https://ocaml.org/manual/latest
* https://ocaml.org/manual/$(VERSION)

https://ocaml.org/manual - HTTP 302 -> https://ocaml.org/manual/$(VERSION) https://ocaml.org/manual/latest - HTTP 302 -> https://ocaml.org/manual/$(VERSION) https://ocaml.org/manual/$(VERSION) serves the actual content and is to be indexed by search engines

Why?

1. We should have only place where the manual for a particular version is being served, or else we have to use the rel="canonical" link in the page header to tell search engines to only index the canonical location.
2. In the long term, users of ocaml.org should never see the redirecting URLs in their browser. As users commonly copy their browser URL bar to share links, this will increase overall backlink quality and makes it more obvious which OCaml version people were talking about in conversations, tutorials and blogs they publish all over the web.

[gasche]

All your proposals are definitive improvements, and I'm in favor of any. (Any opinion on what the gray "version 4.14" link in the top left corner should point to?)

@sabine with the scheme that you propose, users will frequently end up on manual pages that are not the latest version. We need the UI to make it clear, and provide an easy way to jump to the "latest" version of the page if it exists. (In particular, users should not have to know the latest version number for this. If they don't know of the latest/ support in the URL, they will not be able to use it reliably for this purpose.)

[Julow]

If they don't know of the latest/ support in the URL, they will not be able to use it reliably for this purpose.

This should be solved with a select element on the page, right ? I'm not a fan of having the same content on two URLs and definitely prefer the redirection latest -> specific version, as long as we can make that clear inside the page.

[gasche]

Sure, and I think "a select element on the page" is possibly the right thing to replace the current "version 4.14" link that goes to a probably-not-what-you-were-hoping place. But the UI needs a bit of care, because just listing all available versions is very noisy. For example the dune documentation offers exactly two links in its selection panel (reachable from the bottom: v : stable), "stable" and "latest". This is more useful.

Also, just having a discreet select element somewhere on the page is probably not going to solve the problem of "users end up on an old-version manual page from a blog post, they visit the manual expecting to apply the documentation to their current development environment, and they miss all the stuff of newer versions". If you make it so that users almost-only find fixed-version links, there should be a clear signal on the page that they are browsing an outdated version. (At the very least, the select-menu should not be in hard-to-read gray.)

[sabine]

@sabine with the scheme that you propose, users will frequently end up on manual pages that are not the latest version. We need the UI to make it clear, and provide an easy way to jump to the "latest" version of the page if it exists. (In particular, users should not have to know the latest version number for this. If they don't know of the latest/ support in the URL, they will not be able to use it reliably for this purpose.)

Agree that the manual UI should refer to "latest" version and

1. make it easy to get a link to https://ocaml.org/manual/latest, if that's the intent of the user sharing the link. In many cases, content is written and questions are answered relating to a particular OCaml version, and thus, encouraging people to link the versioned URL by technical means makes sense. However, the use case where you want to refer to the latest version does exist, and we must cover that in the UI.
2. make it easy to switch versions quickly to the latest version.

Neither of those UX goals require serving the manual's HTML content unter the URL https://ocaml.org/manual/latest

It seems reasonable that there should be a prominent link that says "latest version" on every manual page (together with the version switcher) and that is easy to click and copy.

[Julow]

If you make it so that users almost-only find fixed-version links, there should be a clear signal on the page that they are browsing an outdated version.

Good idea! A banner kind of element that's hard to miss should explain that.

make it easy to get a link to https://ocaml.org/manual/latest

Yes, the "latest" url should be written down on the page somewhere. I suggest that in the version selector, the "Latest" link should use it.

[sabine]

I'm currently sketching navbar ideas, these are not final by any means.

ETA: for the version switcher: on mobile, it should be a select, on bigger screens, I think the ideal solution would be a bit like github's branch selector UI (so a text box to search and scrollable list of versions). :thinking:

ETA2: we won't have to consider a "stable" version, right? Like... latest will always be the latest stable version, and if we have unstable versions, they should be reachable via the version selector?

ETA3: So after considering a bit more, I think there is also a case to be made in favor of making people link to the latest version of the manual by default. After all, OCaml is overall very backwards compatible.

This would mean a URL scheme https://ocaml.org/manual -> redirect to https://ocaml.org/manual/latest https://ocaml.org/manual/latest serves latest manual https://ocaml.org/manual/($VERSION != latest) serves language manual of $VERSION https://ocaml.org/manual/($VERSION == latest) redirect to https://ocaml.org/manual/latest And a UI more along these lines:

[gasche]

ETA2: we won't have to consider a "stable" version, right? Like... latest will always be the latest stable version, and if we have unstable versions, they should be reachable via the version selector?

Yes.

Regarding your mockup: I'm not sure what "copy link to latest version" is doing / is for. The "jump to latest version" is nice; it could be useful to give the latest version number there. This makes for a long button, so maybe "version" could be moved before the select element instead.

"OCaml language manual       version 4.13.1 ▼       Jump to latest (5.0.0)"

"OCaml language manual       version 5.0.0 (latest) ▼"

[sabine]

or together with

on a scheme that serves under /manual/latest and redirects the latest version's explicit URL to /manual/latest.

I can only speculate, but it actually does seem plausible that the use case of people wanting to link to a specific version of the manual is rarer than them wanting to link to latest. And this UX consideration needs to inform the choice of URL setup, as the more common use case should be the one that has the more obvious solution (copying URL from browser URL bar).

(Here: "copy link to this version" copies the https://ocaml.org/manual/5.0.0 link to the user's clipboard)

[dbuenzli]

You can likely drop the Jump to.

[gasche]

So if I understand correctly, "copy link to this version" is intended to fix the issue that, with your proposed URL rewriting scheme, it is not easy to get hold of the fixed-version URL of the manual when the version happens to be the latest version". "to this version" means "to this specific version rather than the time-varying 'latest' link that is in your URL bar".

Another proposal to fix this problem, which I find simpler, is to simply have separate user-identified pages for "the 5.0.0 version of the manual" and "the latest version fo the manual" -- just like on github I can use trunk/ and <head commit>/ in the URL and get the same thing, with two different behaviors, with neither URL silently rewritten into the other. By default, users navigating through the manual or following latest/ link end up on the latest page, and they refer to those URLs as well. If they want to get to a fixed-version URL, they use the select menu.

"OCaml language manual       latest version (currently 5.0.0) ▼       permalink"

"OCaml language manual       version 5.0.0 ▼       latest version"

"OCaml language manual       version 4.13.1 ▼       latest version (5.0.0)"

The behavior of 5.0.0 page is slightly weird because "latest version" links to the same manual version with a different URL. But, again, users are less likely to end on this page during the time window where it is actually the latest version, and there is no harm in clicking on a link and ending up in the same place.

[sabine]

@gasche Alright, having latest and all versions exist at the same time is reasonable, and indeed, then the version dropdown leads to the specific version URL in case the user wants to share that. :+1:

There's two ways how to get a permalink when you need one (version switcher and permalink button) and they are both discoverable. :+1:

Search engines index https://ocaml.org/manual/latest only, to prevent search engines from choosing the specific version URL as the canonical one. Since all manual versions share a lot of content, it is best we just let them index the latest manual. :+1:

• [ ] update rendering of manual to include version switch UI
• [ ] robots.txt allows https://ocaml.org/manual/latest and disallows https://ocaml.org/manual so that different manual pages do not compete with each other for attention.
• [ ] configure URLs to serve manuals under ocaml.org

https://ocaml.org/manual -> 302 redirect https://ocaml.org/manual/latest

https://ocaml.org/manual/latest -> serve HTML manual of the latest version rendered with the knowledge that it is the latest version.

https://ocaml.org/manual/$VERSION -> serve HTML manual of this version rendered under assumption that it is not the latest version

Now this feels reasonable and it turns out it was worthwhile to look at all the details and requirements.

[dbuenzli]

When you are on the latest version there should be no actionable item to the latest version to make it clear you are already there.

I wouldn't however recommend a disabled button. That's the kind of problems you run into when links are styled to look like buttons which is bad usability. Buttons are for actions, not for navigation.

If these were links you would generally have a link on latest (5.0.0) and the same text but not linked when it's the latest. In fact that's the proper way navigation menu items should work as well, i.e. no link when you are on the page of the menu item.

[gasche]

@dbuenzli when you are on manual/5.0.0, the "latest" link goes to manual/latest, which is a different URL. When you are on manual/latest, "permalink" goes to manual/5.0.0. I don't have a strong opinion on whether the "latest" link should be less visible when you are on the fixed-latest version, but I suspect that uniform behavior is better than special cases here.

[dbuenzli]

@dbuenzli when you are on manual/5.0.0, the "latest" link goes to manual/latest, which is a different URL.

As long as that one does not redirect on the one you are on that's ok – I thought that was the case.

[sabine]

@dbuenzli You're correct that call-to-action buttons should have text that describes what will happen, because buttons could be doing all kinds of things other than nav. I was wrong to shorten it to a description of the target location. We can make the link to latest on the explicit-version URL of the latest version a regular nav item:

Ok, two workable alternatives have been identified. Let's make a decision on URL structure by voting:

Option A :rocket:	Option B :eyes:
https://ocaml.org/manual/latest permalink nav item leads to https://ocaml.org/manual/5.0.0	https://ocaml.org/manual/latest permalink nav item copies https://ocaml.org/manual/5.0.0 to the clipboard
https://ocaml.org/manual/5.0.0	https://ocaml.org/manual/5.0.0 -> 302 redirect to https://ocaml.org/manual/latest until next release
https://ocaml.org/manual/4.13.1	https://ocaml.org/manual/4.13.1

Vote by adding your preference as an emoji (:rocket: : or :eyes:) on this post.

Design can still be discussed, but I would like to see the manual move to its final location ASAP, so we got to decide if there's a redirect from explicit-version URL of latest manual to /manual/latest

[cuihtlauac]

@sabine can you explain why the rel="canonical" option is not good?

[sabine]

@sabine can you explain why the rel="canonical" option is not good?

rel="canonical" is a perfectly good way to make sure only https://ocaml.org/manual/latest gets indexed. For that, we need to modify manual HTML generation to include the rel="canonical" link. The only question is what can we deploy faster: update the manual HTML generation to include rel="canonical" or configure robots.txt.

As soon as search engines index multiple manual versions, they will find that the content is extremely similar and then they go ahead and choose a canonical page. Might be the one we intended, or not. So, we can configure robots.txt now, as a workaround for not yet having rel="canonical" in the HTML page headers (if that is quicker to set up).

[cuihtlauac]

Thanks for the explanation, @sabine.

On scenario A / https://ocaml.org/manual/latest: labelling the permalink as “version permalink” or “5.0.0 permalink” may help to understand it's not pointing to the address of the page.

I also support what @dbuenzli wrote:

When you are on the latest version there should be no actionable item to the latest version to make it clear you are already there.

Assuming “latest” in the above means /x.y.z (as opposed to /latest).

[gasche]

Hi all,

Do you have any news of potential progress on this issue? Today, if I go to a random page of the manual, for example https://v2.ocaml.org/manual/intfc.html#ss:c-prim-impl, I still don't know how to get a permanent link.

[gasche]

This is still an issue for me, every time I need to access the reference manual to provide an URL for other people.

[sabine]

@gasche we are actively working on moving the manual from v2.ocaml.org to ocaml.org now.

[gasche]

(I mentioned the manual again today and was reminded of this issue.)

[cuihtlauac]

@gasche: Since the migration of the manuals from v2.ocaml.org (PR #2150) and tweaking of the redirects (PR #2358), here is what is supported:

Versioned manual and API pages live under ocaml.org/manual/<VERSION>/<PAGE> and ocaml.org/<VERSION>/api/<MODULE_PAGE>, for instance:

• https://ocaml.org/manual/5.2/index.html
• https://ocaml.org/manual/4.14/language.html
• https://ocaml.org/manual/5.1/api/Arg.html

<VERSION> can be:

• a valid version number between 3.12 and the latest release
• latest which is an alias for the latest release (currently 5.2)
• lts which is an alias for 4.14
• missing which is an alias for the latest release
• If <VERSION> is X.Y.Z, .Z is removed
• If <VERSION> is X, the largest known .Y is added

/<PAGE> is optional, if missing, it redirects to /index.html

In v2, there was:

https://v2.ocaml.org/releases/4.14/htmlman/index.html https://v2.ocaml.org/releases/4.14/api/Arg.html

We currently don't support

https://ocaml.org/releases/4.14/htmlman/index.html https://ocaml.org/releases/4.14/api/Arg.html

But we could add that too.

[gasche]

Thanks! This sounds like it fixes the problem for me: if I browse the manual through the web, I will end up on a URL that I can easily tweak to get any version I want. (This was not the case before.)

[gasche]

In this issue a lot of potential UI choices were discussed to show this flexibility to users (let them jump to another version, or ask for the latest version, get a permalink etc.). Are those mockups still planned for later, or should we close the issue because a "good enough" behavior now exists?

(I remain confused by the behavior of the "Select another version" link in the left column, but oh well.)