dart-lang
Make version-agnostic URLs the default
[Copied from https://github.com/dart-lang/dartdoc/issues/1074.]
People are constantly linking to, say, https://api.dartlang.org/1.12.1/dart-core/Object-class.html when they should instead be linking to https://api.dartlang.org/stable/dart-core/Object-class.html (or maybe a shorter URL like https://api.dartlang.org/dart-core/Object-class.html).
We should make it easier to get a good permalink. This could be combined, somehow, with showing the current version and a way of switching to the stable/dev version of the docs.
Personally, I'd rather have the displayed URL be generic (https://api.dartlang.org/dart-core/Object-class.html) unless you choose a particular version.
An (extreme) example of this is in the AngularJS docs:
The docs for angular.bind are in https://docs.angularjs.org/api/ng/function/angular.bind. A dropdown at the upper left shows which build the docs reflect. If you want another build, you can choose it from the dropdown. For example, if you use v1.4.8, then the URL switches to https://code.angularjs.org/1.4.8/docs/api/ng/function/angular.bind. (It's difficult to get back to the real "latest", so ... not a perfect solution.)
To repeat: We should make it easy for people to do the right thing, which I believe is linking to the latest stable version of the docs. We should make it possible to link to other docs, with minimal effort on the linker's part.
@sethladd suggests a domain-channel-based scheme. Something like this:
- api.dartlang.org (latest stable)
- dev.api.dartlang.org (latest dev)
- be.api.dartlang.org (latest bleeding edge build)
If we needed to point to multiple stable channel releases, then we'd need to add something to the URL... but at least you'd always be able to easily point to the latest stable version of the docs.
Whatever we use, it should be easy to figure out which channel+version the docs are for.
Latest I realized that my proposal doesn't really solve the problem. We would still need a way to version specific stable API sets (for 1.14.1, 1.14.2, etc)
I suppose that's true. But I still want version agnostic links to be the default. So maybe instead of showing https://api.dartlang.org/stable/1.16.1/dart-core/String-class.html, show api.dartlang.org/dart-core/String-class.html.
Or if that's not possible, show (not just allow, but actually show in the URL field or prominently in a Copy a link to the latest version of this page icon at the top of the page) URLs like api.dartlang.org/stable/dart-core/String-class.html, api.dartlang.org/dev/dart-core/String-class.html, and api.dartlang.org/be/dart-core/String-class.html.
I really just want all version #s out of the URLs that people see and use, except in the rare case when you actually care about tracking that version, even when new ones exist. So it should be possible to get docs for a specific version, but far easier to get docs for the latest stable version.
I'd still REALLY like this change. I was just kvetching to a bunch of OSS writers about this issue.
To be more specific, I'd like to have the visible URL feature words, not numbers. Currently the version is always embedded in the page's visible URL. Our docs avoid using numbers, but when users follow those links, they see those numbers.
For example, our docs use URLs like this:
- https://api.dartlang.org/stable/dart-convert/JsonCodec-class.html
- https://api.dartlang.org/dev/dart-convert/JsonCodec-class.html
- https://api.dartlang.org/be/dart-convert/JsonCodec-class.html
But our users see (and copy and paste) URLs like this:
- https://api.dartlang.org/stable/2.0.0/dart-convert/JsonCodec-class.html
- https://api.dartlang.org/dev/2.1.0-dev.3.0/dart-convert/JsonCodec-class.html
- https://api.dartlang.org/be/158074/dart-convert/JsonCodec-class.html.
Here's what I'd like to both use and see (I'll drop the .html because that'd be nice, too):
- https://api.dartlang.org/dart-convert/JsonCodec-class (the stable docs)
- https://api.dartlang.org/stable/dart-convert/JsonCodec-class (use only; not to be seen)
- https://api.dartlang.org/dev/dart-convert/JsonCodec-class
- https://api.dartlang.org/be/dart-convert/JsonCodec-class
What do you think?
/cc @kevmoo @jcollins-g
In case you needed an update, the question of URLs keeps coming up. For example, recently a DPE was using random stable version numbers (returned by Google search) in an article. And in https://github.com/dart-lang/site-www/issues/2518, I had to tell someone how to check the latest version of the generated API docs (which implies also that we should make the different channels of docs visible in the UI).