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

Initial attempt at combining tutorials and codelabs #4875

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

mit-mit
Copy link
Member

@mit-mit mit-mit commented May 12, 2023

Issues with the current design:

  • There is no functional difference between tutorials and codelabs; for the purposes of our docs there's no reason to distinguish them (I'll be using "tutorials" referring to both, as the docs should)
  • The positioning of "Tutorials & Codelabs" right at the top of the sidenav is misrepresentative - it implies that's a good place for users to start exploring the docs.
  • A aggregate "tutorials" page should have them listed in some sort of logical progression of skill building, and that progression should be complete. Not the case here.

After some discussion, here's how we've decided to progress with solving this:

  1. Add a preliminary "Getting Started" page to the top of the sidenav

    • Single page, summarizes key areas of the docs site and how to progress through them, why you might need each one. Could include pointers to tutorials, as well as language tour pages, anything.
    • Focus on Language, Libraries, and the Command-line app tutorial
    • I'm thinking the page should have a very light narrative calling out the highlights of each topic-area the docs cover, in the order that makes sense for the typical new user's goals. Rough example, but something like:
      • "To start using Dart, familiarize yourself with some of the syntax on these pages (link(s) to some of the better introductory examples we have, the command-line app tutorial for a more in-depth intro, etc.)....."
      • "Dart is an object oriented language, so make sure to read about classes and their behaviors over here..... "
      • "To build real programs, you'll need to understand Dart's core libraries and what they offer, so skim through this to get a an idea....(library tour, whatever)..... "
      • "The Dart ecosystem uses packages to manage shared software, so next you should learn how to effectively manage your own software as packages, as well as how to utilize our rich package library over here....."
      • "Dart is meant to be a powerful solution to developing multiplatform apps. Learn about development tools and tips for Dart over here best development section basics page..... "
  2. Remove the "Tutorials & Codelabs" section from the side nav

    • Re-position the tutorials listed on those pages alongside their overarching topic pages
    • E.g., How the "Write command line apps" and "Write HTTP servers" tutorials are listed under "Development" > "Command line & server apps" already
    • (@parlough is this essentially how the Flutter IA restructure is working out? Any advice before we get started?)
  3. Change all mentions of "codelab" to "tutorial" across the site

@mit-mit mit-mit changed the title Early beginnings Initial attempt at combining tutorials and codelabs May 12, 2023
Copy link
Contributor

@atsansone atsansone left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mit-mit : Love this suggestion. I added a few notes.

Comment on lines +12 to +18
If you like learning via coding exercises
checkout the [Dart koans](/codelabs/dart-cheatsheet).
For a more textual introduction see the
[language intro](/language).
The Language menu on the left also has tutorials
on more detailed topics, and tutorials written
for those with existing knowledge of other programming languages.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: Need to add commas to the dependent clauses.

Suggested change
If you like learning via coding exercises
checkout the [Dart koans](/codelabs/dart-cheatsheet).
For a more textual introduction see the
[language intro](/language).
The Language menu on the left also has tutorials
on more detailed topics, and tutorials written
for those with existing knowledge of other programming languages.
If you like learning via coding exercises,
check out the [Dart koans](/codelabs/dart-cheatsheet).
To get an in-depth explanation, see the
[language intro](/language).
The Language menu also includes tutorials on more
detailed topics and for those with existing knowledge
of other programming languages.

Comment on lines +22 to +23
The Libraries menu contains tutorials on the Dart core libraries,
including collections, math, asynchronous programming, and I/O.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: We don't need to describe the TOC. We can link to it.

Suggested change
The Libraries menu contains tutorials on the Dart core libraries,
including collections, math, asynchronous programming, and I/O.
Libraries contains tutorials on the Dart core libraries,
including collections, math, asynchronous programming, and I/O.

Comment on lines +10 to 13
This tutorial teaches you about Dart’s [null-safe type system](/null-safety),
which was introduced in Dart 2.12. When you opt into null safety,
types in your code are non-nullable by default,
meaning that values can’t be `null` unless you say they can be.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Write as shorter sentences per GSG.

Suggested change
This tutorial teaches you about Dart’s [null-safe type system](/null-safety),
which was introduced in Dart 2.12. When you opt into null safety,
types in your code are non-nullable by default,
meaning that values can’t be `null` unless you say they can be.
This tutorial explains Dart’s [null-safe type system](/null-safety).
Dart 2.12 introduced null safety and Dart 3 made it the default setting.
With null safety, types in your code default to non-nullable.
This means that values can’t be `null` unless you say they can be.

@@ -22,7 +22,7 @@ This codelab covers the following material:

Using embedded DartPad editors, you can test your knowledge by
completing and running exercises. To get the most out of
this codelab, you should have some knowledge of [basic Dart syntax](/language).
this tutorial, you should have some knowledge of [basic Dart syntax](/language).

{{site.alert.note}}
This page uses embedded DartPads to display exercises.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Add a link to DartPad.

Suggested change
This page uses embedded DartPads to display exercises.
This page uses embedded [DartPads](/tools/dartpad) to display exercises.

Comment on lines +539 to 540
Congratulations, you've finished the tutorial! If you'd like to learn more, here
are some suggestions for where to go next:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Phrase as a call to action and avoid "here".

Suggested change
Congratulations, you've finished the tutorial! If you'd like to learn more, here
are some suggestions for where to go next:
Congratulations, you've finished the tutorial!
To learn more about null safety, we suggest the following topics:

Comment on lines +549 to 552
If you're interested in using embedded DartPads, like this tutorial does, see
[best practices for using DartPad in tutorials](/tools/dartpad/dartpad-best-practices).
If you're interested in improving this codelab, see
If you're interested in improving this tutorial, see
[issue #3093][].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: This page isn't about DartPad, so I would delete that reference. Also, I don't recommend linking to the issue. The page has a button that can be clicked to review the code, then create an issue or PR.

@atsansone atsansone added the review.await-update Awaiting Updates after Edits label May 15, 2023
@MaryaBelanger MaryaBelanger self-assigned this Jul 12, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
review.await-update Awaiting Updates after Edits
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants