search

dart-lang / api.dart.dev

Dart API docs
https://api.dart.dev
BSD 3-Clause "New" or "Revised" License
19 stars 17 forks source link

Make version-agnostic URLs the default #53

Open kwalrath opened 8 years ago

kwalrath commented 8 years ago

[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:

image

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.

kwalrath commented 8 years ago

@sethladd suggests a domain-channel-based scheme. Something like this:

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.

sethladd commented 8 years ago

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)

kwalrath commented 8 years ago

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.

kwalrath commented 6 years ago

I'd still REALLY like this change. I was just kvetching to a bunch of OSS writers about this issue.

kwalrath commented 6 years ago

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:

But our users see (and copy and paste) URLs like this:

Here's what I'd like to both use and see (I'll drop the .html because that'd be nice, too):

What do you think?

/cc @kevmoo @jcollins-g

kwalrath commented 3 years ago

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).