site-www
site-www copied to clipboard
dart-lang
Consider consolidation of pages covering asynchrony/generator support
It feels like there is an opportunity for consolidation. Here are pages that discuss, in varying detail, asynchrony (and sometimes generator) support in Dart:
- Language Tour: Asynchrony support
- Library Tour - dart:async
- Articles:
-
~~Dart Language Asynchrony Support: Phase 1~~ Deleted. Forwards to the Future/async/await codelab.
-
~~Dart Language Asynchrony Support: Phase 2, also covers generators.~~ Deleted. Is the top 404 on dart.dev, with 9% of the 404s for the past 30 days (as of 2020/2/14). Archived copy (thank you archive.org!)
-
- Tutorials:
It might also be worth examining relevant API entries:
I understand that each one of the following has a different purpose (and potentially a different audience): tour, article, tutorial, and API page. But it feels like there is too much repetition. (Oh, and of course, there is the Language spec.)
I also understand that the pages listed above emerged over time, but in moving to Dart 2, we have an opportunity to consolidate these pages, rather than just update them all.
cc @kwalrath @kevmoo
There's also the article The Event Loop and Dart, which is currently on webdev but I think is applicable to Flutter.
I agree we should think about this. How do you think people approaching Dart (as neophytes or experienced Dart programmers) think about these topics? Futures are important conceptually, but many people won't use the Future API for quite a while (if ever). Similarly, a lot of people will only consume Streams, and in only limited ways. How do we make sure people can easily get the minimum knowledge they need quickly, but also be able to learn more once they need to?
Some thoughts about individual docs:
- The language tour & library tour will probably stay more or less as-is, although coverage of individual topics could be added or removed or shrink (if it's too detailed and covered elsewhere). People like having a single page they can search to find simple explanations of the main language and library features.
- I want to move the important parts of all the articles into real docs, and remove the articles.
- I'm not sure about the tutorials. They're approachable, but they predate codelabs and DartPad and will need to be updated (at the very least) for Dart 2.
And also Futures and Error Handling, which somehow didn't make its way onto the list in #407. It's the 60th most viewed page on the site.
