Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
MaryaBelanger opened this issue Jun 7, 2023 · 3 comments
Open
Labels
d.enhancement Improves docs with specific ask dev.concurrency Relates to concurrency e1-hours Can complete in < 8 hours of normal, not dedicated, work from.team Reported by Dash docs team member infra.ia Relates to the organization of pages and structuring of content p3-low Valid but not urgent concern. Resolve when possible. Encourage upvote to surface. st.triage.ltw Indicates Lead Tech Writer has triaged

Comments

@MaryaBelanger
Copy link
Contributor

MaryaBelanger commented Jun 7, 2023

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 MaryaBelanger changed the title Async different page title and sidenav title Different page titled and sidenav titled Jun 7, 2023
@MaryaBelanger
Copy link
Contributor Author

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"

@atsansone atsansone changed the title Different page titled and sidenav titled Choose one title for Async page (page and sidenav titles differ) Jun 7, 2023
@atsansone atsansone added d.enhancement Improves docs with specific ask p3-low Valid but not urgent concern. Resolve when possible. Encourage upvote to surface. e0-minutes Can complete in < 60 minutes of normal, not dedicated, work st.triage.ltw Indicates Lead Tech Writer has triaged labels Jun 7, 2023
@parlough
Copy link
Member

parlough commented Jun 7, 2023

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.

@parlough parlough added e1-hours Can complete in < 8 hours of normal, not dedicated, work infra.ia Relates to the organization of pages and structuring of content dev.concurrency Relates to concurrency and removed e0-minutes Can complete in < 60 minutes of normal, not dedicated, work labels Jun 7, 2023
@atsansone
Copy link
Contributor

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.

@atsansone atsansone added the from.team Reported by Dash docs team member label Aug 8, 2023
@atsansone atsansone assigned atsansone and unassigned atsansone Jun 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
d.enhancement Improves docs with specific ask dev.concurrency Relates to concurrency e1-hours Can complete in < 8 hours of normal, not dedicated, work from.team Reported by Dash docs team member infra.ia Relates to the organization of pages and structuring of content p3-low Valid but not urgent concern. Resolve when possible. Encourage upvote to surface. st.triage.ltw Indicates Lead Tech Writer has triaged
Projects
None yet
Development

No branches or pull requests

3 participants