Evaluate and/or rewrite the FAQ

[parlough]

Page URL

https://dart.dev/resources/faq

Page source

https://github.com/dart-lang/site-www/tree/main/src/faq.md

Describe the problem

Most of the FAQ entries were written a long time ago. While many still be correct, a lot of them may be outdated or irrelevant, or import questions may be missing. Most of them are focused on the web, which has overall modified focus and web interop and web features are evolving heavily in the near feature. Our writing style has evolved since then as well.

Expected fix

Evaluate each FAQ entry for its:

1. Usefulness
2. Correctness
3. Writing

Then either remove or update it accordingly.

Also consider other frequent questions that may be useful to add.

Additional context

No response

[parlough]

I think in the end, we should likely start from the ground up, considering what questions new and existing Dart developers are asking today. The questions and our answers will likely be very different than a few years ago. Some initial thoughts about existing content:

---

Some entries should be updated or removed in relation to recent Dart changes, particularly in Dart 3:

• Q. Is there a specification for Dart?
  Some entries refer to Dart 2. They should be updated to say "2 and 3" or only 3.
• Q. Can Dart add tuples, pattern matching, partial evaluation, optional semicolons, …?
  Dart is aiming to add records and pattern matching in Dart 3.

Some of the details documented in the FAQ should be elsewhere:

• Supported web deployment platforms: We should likely document this in the dart compile js documentation and consider documenting similar information for other dart compile sub-commands.

Various JS and web related questions that will likely need large changes in the future as web interoperability evolves with inline classes, package:web, dart2wasm, changes to package:js, etc:

• Q. How does Dart code interoperate with JavaScript libraries?
  Q. I have a large JavaScript codebase. How can I migrate it to Dart?
  We mention interoperability a few times here so may need to make some updates or change some links.
• Q. I have a large app written in GWT. How do I port it to Dart?
  Is this relevant(frequent) enough anymore to have a home in the FAQ?
• Q. Why does Dart have two ways to compile to JavaScript?
  dart2wasm will exist in the future.
• Q. How does Dart compare with CoffeeScript?
  This question may not be super relevant anymore now that TypeScript has taken over that scene.

Some potential new topics:

• We maybe should consider adding general question about wasm support (both loading and compiling to)
• We mention some other languages, but one common question is about different to kotlin, especially since it has been embraced by Android. We should consider a question about it, similar to how we have one about Go.

[parlough]

@mit-mit @kevmoo @atsansone The faq in its current state is not that useful nor does it reflect much of Dart's current state/usage. Outside of a few updates, it's still written from the perspective of focusing on web programming and the prospects of web tooling like AngularDart or moving away from Java/GWT. The page also has an extremely low visitor count over the past few months, suggesting users aren't searching for these questions anymore.

Would you be fine with scrapping this page for now? Or are there some newer questions you'd like to see answered here?

I'm personally leaning towards scrapping it, as any question that is still worth answering should be covered either in the Overview or its own relevant documentation. Let me know what you think :)

[eernstg]

I think we do have some useful FAQs. For example, web number semantics vs. native number semantics (doesn't seem to be in the FAQ at this time), "why is the least upper bound of Iterable<int> and List<num> not Iterable<num>?" (also missing), and a bunch of other questions that are actually frequent. I wasn't aware of the FAQ, but it seems like a really nice place to point to each time one of those frequent questions comes up again.

Maybe you could keep the page and just remove questions/answers that are obsolete? This would ensure that existing bookmarks keep working, and there's a certain style for an entry that authors of new entries can use.

(OK, it's a non-trivial exercise to find the obsolete entries, and just the obsolete ones. But I'd expect that effort to be useful, so it's probably worth the time to do it.)