search

dart-lang / site-www

Source for Dart website
https://dart.dev
Other
965 stars 695 forks source link

Choose one title for Async page (page and sidenav titles differ) #4965

Open MaryaBelanger opened 1 year ago

MaryaBelanger commented 1 year ago

Page URL

https://dart.dev/language/async

Page source

src/language/async.md

Describe the problem

The title of the page is "Asynchrony support", but the sidenav title is "Asynchronous support". The next/prev buttons just say "Async" (idk if that's as important, maybe it's fine for the buttons to be abbreviated).

They should be the same.

Expected fix

Idk if one is better/more accurate. If there's no difference, I'll just choose one.

Additional context

No response

MaryaBelanger commented 1 year ago

Just noticed another one, "Concurrency in Dart" is the page title, but in the sidenav it says "Isolates", and in the next/prev buttons it just says "Concurrency"

parlough commented 1 year ago

Sorry, this got a bit rambly...if something doesn't make sense let me know.

I think it's good to have alignment where it makes sense, but note that the sidenav and titles can and sometimes likely should differ. One is for drawing attention within the context of the sidenav, while the full title is providing information in the context of the page and more often in external search. Beyond that, the full titles are sometimes too long to represent neatly in the sidenav as well. This happens relatively often on the Flutter site.

As for the prev/next text, I feel they often should be shorter, and the future generator for them will likely use the short-title frontmatter if one is specified. I'm happy to adjust that behavior though :)

In terms of the async doc, "Asynchronous support" reads a bit weird since asynchronous is an adjective. On the other hand, "Asynchrony" might be a foreign term for many. How about "Asynchronous programming"?

The "Concurrency in Dart" page is tricky since I think a better title in the sidenav is "Concurrency", but that would be a bit awkward in a section already title concurrency. The doc also already repeats some of the concepts of the Async doc. I guess this is because it wasn't originally part of the language tour. Now that they are side by side, perhaps we need three articles: "Overview" (Concurrency in Dart overview), "Asynchronous programming" (async/await), and "Isolates". Or just two: "Overview" (overview and async/await), then "Isolates". That requires more work but would fix the issue and improve the docs overall. A bit unrelated, but we also link to the async/await codelab in a few places for more information which doesn't seem great, we should try to update the async language docs to be more complete as part of this.

atsansone commented 1 year ago

For my two cents, the larger issue is parallelism on the left nav, which is, essentially, a list. (See GSG.) Most of the entries on the left nav are just nouns. That's great. Some second levels are verb noun, but consistent at that level.

Recommend trying to keep the left nav title consistent within the navigation. If it differs on the page, no real problem there.