flutter
Updates related to go links
As @sfshaza2 and other DevRel folk discussed yesterday, we'd like to have go links be parallel between dart.dev & flutter.dev, and we need to make sure that go links are listed correctly. Some thoughts:
- Easy:
- Update https://flutter.dev/docs/resources/design-docs to be clear that not all of the docs listed are design docs.
- Add a go/go redirect that takes you to that page. :)
- Requires some thought/effort:
- Consider a new convention to differentiate design docs vs. other go links.
- Consider regularizing short links that don't start with go — convenience redirects.
Yes, we had a good discussion about this in the Dart DevRel sync. The "/docs/resources/design-docs" index page generates the list of "go" links and introduces them as the list of design docs. (Even the file name states "design docs". This was true, originally, but the go links have proved so useful, that they are now being used in other instances and we have no way of distinguishing between them.
We should consider doing the following (but it's still up for discussion):
- Specifically use "go" links for design docs, OR rename the go link for design docs.
- Add a new "short" link designation for "go" links that aren't actually design docs. For example, for tooling that wants to point users to a nice short link instead of a hugely deep URL.
- I love the idea of adding a "go/go" link!
- Follow the same approach on the dart.dev site with the Dart "go" links.
We are open to suggestions, @Hixie, @tvolkert. Please cc in others who might care/have a stake in this.
Docs with go/ links are intended to be of short-lived usefulness, and their long-term existence is for historical interest only. They aren't supposed to be used for long-term documentation and are generally unlikely to be of interest to the wider community beyond those working on Flutter itself. As such, tooling shouldn't be pointing to these at all.
I agree that we shouldn't say that all go/ docs are design docs, though. They could be any random docs used during development.
...As such, tooling shouldn't be pointing to these at all.
That's kind of the opposite of the way we use them in Dartland. We often create a go link explicitly for use in tools, because users have to type or copy-paste those links, which (especially if they involve anchors) can be long.
@Hixie what would you propose as a prefix for long-lived docs?
I wouldn't use a prefix. Just a nice memorable URL, like https://flutter.dev/docs/testing/debugging or whatever. It's not really any harder to remember or type than https://flutter.dev/go/debugging-testing-doc or whatever we'd use for that.
That said, if the go/ links in question are just redirects, then they seem somewhat orthogonal to this discussion, since they don't need to be listed at all -- that would be redundant with the web site itself.
Aren't all go/ links redirects? There's no /src/go directory in either repo. Or did you mean something else by redirect?
Below are some examples of go links on dart.dev. Some go to non-dart.dev locations, and some go to dart.dev locations that have longer URLs and/or might change. (e.g. the non-promo-* go links are likely to turn into section links within the page that they currently go to... once those sections exist. We created these links for tools to use in their output.)
{ "source": "/go/dart-fix", "destination": "https://github.com/dart-lang/sdk/blob/master/pkg/dartdev/doc/dart-fix.md", "type": 301 },
{ "source": "/go/data-driven-fixes", "destination": "https://github.com/flutter/flutter/wiki/Data-driven-Fixes", "type": 301 },
{ "source": "/go/experiments", "destination": "/tools/experiment-flags", "type": 301 },
{ "source": "/go/null-safety-migration", "destination": "/null-safety/migration-guide", "type": 301 },
{ "source": "/go/test-docs/:page*", "destination": "https://github.com/dart-lang/test/blob/master/pkgs/test/doc/:page*", "type": 301 },
{ "source": "/go/non-promo-write", "destination": "/tools/non-promotion-reasons", "type": 301 },
{ "source": "/go/non-promo-property", "destination": "/tools/non-promotion-reasons", "type": 301 },
{ "source": "/go/non-promo-this", "destination": "/tools/non-promotion-reasons", "type": 301 },
{ "source": "/go/unsound-null-safety", "destination": "/null-safety/unsound-null-safety", "type": 301 },
{ "source": "/go/sdk-constraint", "destination": "https://dart.dev/tools/pub/pubspec#sdk-constraints", "type": 301 }
Sorry I meant redirects to our own web site as opposed to redirects to Google Docs or other such docs that aren't part of our public documentation portfolio.
FWIW, on the Flutter side there's only two places where we keep long-term written documentation for developers: the API docs, and the web site itself. Everything else, including the wiki, Google Docs, GitHub, etc, is not considered part of our public-facing documentation surface. For example, the wiki is specific to the Flutter team, Google Docs are for the team, and so on.
For URLs that are on our web site, there's no need for a go/ link, since those are also on our web site, and anything we can do to make the go/ links permanent we can equally do to make the other URLs permanent.
I agree with Ian. We should NOT be using the go links for anything except design docs. I've just analyzed our go links and there are 7 that are internal redirects. There are also a few that redirect to GitHub and DartPad. I'd like to replace with non-go links.
I will reach out to the tools teams to verify if any of these are embedded in the tooling and see about changing those to regular redirects (NOT go links).
A redirect to https://flutter.dev/docs/resources/design-docs exists. No link to that or https://docs.flutter.dev/resources/design-docs is in the documentation. This appears to be dead concern. Closing.
