Modernize the Get Started content by BillWagner · Pull Request #51565 · dotnet/docs

BillWagner · 2026-02-09T20:38:27Z

TL;DR: Update the C# "Get Started" section to serve four audiences (Learner, Student, Early-in-career, Professional) by: creating a new workloads overview article, reshaping the two index/landing pages, adding audience signposts and Fundamentals cross-links to all Tour of C# articles and tutorials, and enriching the tips-for-X-developers articles with code comparisons. All samples use file-based apps; Main is covered only in prose. The file-based-programs.md tutorial stays in Fundamentals but gets prominent "next step" links from Get Started.

This should be easier to review commit-by-commit.

Steps

Phase 1 — New content

Create docs/csharp/tour-of-csharp/what-you-can-build.md — A new, short article (target ~150–200 lines) titled "What you can build with C#." Organize it as a brief intro paragraph explaining that C# and .NET support many workloads, followed by subsections with 2–3 sentences + key links for each workload:
- Web (ASP.NET Core, Blazor, minimal APIs)
- Desktop (WPF, WinForms, .NET MAUI on Windows/macOS)
- Mobile (.NET MAUI for iOS/Android)
- Cloud & microservices (Azure SDK, .NET Aspire, Worker Services)
- IoT (docs/iot/index.yml)
- AI & machine learning (ML.NET, Semantic Kernel, Azure AI)
- Gaming (Unity, MonoGame, CryEngine)
- Add an audience callout box: Learners/Students → "Pick any workload later; focus on learning the language first." Professionals → "Jump directly to the workload that matches your job."
- Set ms.date: 02/06/2026, add ai-usage: ai-assisted.
Add what-you-can-build to the TOC — Insert it in docs/csharp/toc.yml under "Get started," after "Tour of C#" and before the tutorials block.

Phase 2 — Reshape landing/hub pages

Reshape the "Get started" card in docs/csharp/index.yml — In the productDirectory → "Get started" card, update links to:
- A tour of C# (overview.md) — unchanged
- What you can build (what-you-can-build.md) — new
- Beginner C# tutorials (tutorials/index.md) — unchanged
- C# for Java / JS / Python developers (tips-for-java-developers.md) — new link
- C# for beginners video series — unchanged
- Foundational C# Certification — unchanged
Remove the "Try C# in your browser" and "Inside a C# program" links (those are reachable from the tutorials and tour). Update ms.date: 02/06/2026.
Reshape docs/csharp/tour-of-csharp/index.yml — Reorganize the landing page to guide four audiences:
- Rename "Learn to program" section → "Choose your path" and restructure its link lists:
  - New to programming? — tutorials/index.md, hello-world.md, beginner video series
  - Experienced developer new to C#? — overview.md, tips-for-java/js/python links, what-you-can-build.md
- In "Fundamentals," add a link to file-based-programs.md as a "Build your first app" entry.
- In "Key concepts," keep the tips-for-X articles, add what-you-can-build.md.
- Remove the "Advanced concepts" and "C# language standard" sections from this landing page (they're accessible from the main hub). This keeps the Get Started landing page focused on beginners-through-intermediates.
- Update ms.date: 02/09/2026.

Phase 3 — Update Tour of C# articles

Edit docs/csharp/tour-of-csharp/overview.md — Changes:
- Add audience guidance near the top: a short "Who this article is for" note addressing all four audiences with suggested reading paths.
- Edit the content to make sure it's approachable for beginners while still useful for experienced developers.
- Ensure the Hello World example uses file-based apps first (dotnet run hello.cs); Main discussed in a subsequent "Note" block explaining that older code uses this pattern, linking to fundamentals/program-structure/main-command-line.md.
- After each feature area (types, methods, exceptions, etc.), add a "Learn more" link to the corresponding Fundamentals article.
- Add a "What you can build" link near the workloads mention.
- Add a "Next steps" section at the bottom guiding readers to tutorials/index.md, what-you-can-build.md, and fundamentals.
- Update ms.date: 02/09/2026.
Edit docs/csharp/tour-of-csharp/strategy.md — Minor changes:
- Add a brief note at the top: "This article is most relevant for professionals and students who want to understand C#'s design philosophy."
- Add a link to what-you-can-build.md where workloads are mentioned.
- Update ms.date: 02/09/2026.
Edit docs/csharp/tour-of-csharp/tips-for-java-developers.md — Enrichments:
- Add a brief intro targeting "Early in career" and "Professional" audiences coming from Java.
- Add side-by-side code comparison snippets (≤6 lines each, kept inline) for 3–4 key syntax differences: variable declaration, lambda expressions, string interpolation, null handling. Use file-based app style for C# side.
- Add "Learn more" links to Fundamentals after each comparison area.
- Add a "Next steps" section pointing to overview.md, tutorials, and what-you-can-build.md.
- Update ms.date: 02/09/2026.
Edit docs/csharp/tour-of-csharp/tips-for-javascript-developers.md — Same pattern as step 7, but comparing JavaScript/TypeScript with C#. Focus comparisons on: type annotations, async/await, classes, pattern matching.
- Update ms.date: 02/09/2026.
Edit docs/csharp/tour-of-csharp/tips-for-python-developers.md — Same pattern as step 7, but comparing Python with C#. Focus comparisons on: type annotations, list comprehensions vs. LINQ, indentation vs. braces, class definition.
- Update ms.date: 02/09/2026.

Phase 4 — Update tutorials

Edit docs/csharp/tour-of-csharp/tutorials/index.md — Changes:
- Add audience guidance at the top: "New to programming? Start here with tutorial 1. Coming from another language? You can skim tutorials 1–2 and start at tutorial 3."
- Clarify that all tutorials use file-based apps (no project files needed).
- After the tutorial list, add a "What's next?" section that links to:
  - file-based-programs.md as the recommended next tutorial
  - what-you-can-build.md to explore workloads
  - fundamentals/types/index.md for deeper type system learning
- Update ms.date: 02/09/2026.
Edit each tutorial (hello-world.md, numbers-in-csharp.md, tuples-and-types.md, branches-and-loops.md, list-collection.md, pattern-matching.md) — For each:
- Verify all samples use file-based apps (research confirms they already do — validate, don't change unless needed).
- Add a "Learn more" callout box after the first introduction of each key concept, linking to the relevant Fundamentals article. Specific mappings:
  - hello-world.md: strings → types/index.md, methods → program-structure/index.md
  - numbers-in-csharp.md: numeric types → types/index.md
  - tuples-and-types.md: records → types/records.md, interfaces → types/interfaces.md, classes vs structs → object-oriented/index.md
  - branches-and-loops.md: if/else → general programming structure, loops → program-structure/index.md
  - list-collection.md: generics → types/generics.md, collections → link to System.Collections.Generic reference
  - pattern-matching.md: pattern matching → functional/pattern-matching.md, enums → types/index.md
- Ensure each tutorial's "Next steps" links to the next tutorial and to the relevant Fundamentals deep-dive.
- Add brief audience callouts where helpful (for example, in tuples-and-types.md: "If you've used Python tuples or Java records, you'll find these concepts familiar.").
- Update ms.date: 02/09/2026 on each file.

Phase 5 — TOC updates

Update docs/csharp/toc.yml — In the "Get started" section:
- Add what-you-can-build.md entry after "Tour of C#":
```
- name: What you can build
  href: tour-of-csharp/what-you-can-build.md
```
- No other TOC restructuring needed — the current order (Overview → What you can build → Tutorials → Strategy → Tips articles) follows a logical beginner → intermediate progression.

Phase 6 — Verify no legacy articles should move

Review legacy tutorials for relocation — Based on research:
- console-teleprompter.md (2021) and console-webapiclient.md (2022) are dated and use old patterns, but they don't belong in "Get started" — they're intermediate content. No move needed, but flag for future modernization.
- string-interpolation.md overlaps with what hello-world.md teaches. No move — it's a deeper dive that Fundamentals or the tutorials section can reference.
- top-level-statements.md is somewhat superseded by the file-based apps approach. No move — it remains useful as a reference for project-based patterns.

Verification

Build the docs locally: run docfx build and confirm no broken links or build warnings.
Verify all new cross-links resolve: check that every [text](path) and url: in YAML points to an existing file.
Manually walk through the reading path for each audience:
- Learner: hub → tutorials/index.md → hello-world.md → ... → pattern-matching.md → file-based-programs.md → what-you-can-build.md
- Student: hub → overview.md → tutorials → fundamentals
- Early-in-career: hub → tips-for-X-developers.md → overview.md → tutorials (skim) → fundamentals
- Professional: hub → overview.md → what-you-can-build.md → tips-for-X → fundamentals
Confirm all edited files have ms.date: 02/06/2026.
Confirm ai-usage: ai-assisted is set on any newly created .md files.
Confirm all samples in edited files use file-based apps; Main appears only in explanatory prose with a link to main-command-line.md.

Decisions

Workloads article: Creating a new what-you-can-build.md rather than scattering workload links — provides a single destination that all articles link to.
file-based-programs.md stays in fundamentals: Linked prominently from Get Started's tutorials index and landing page as "next steps" rather than relocated — avoids disrupting existing links.
Hub page scope: Only the "Get started" card in productDirectory of index.yml is reshaped; other sections unchanged.
Code comparisons in tips articles: Adding inline snippets (≤6 lines each) rather than extracted files — keeps comparisons immediately visible and doesn't require project scaffolding for multi-language examples.
No legacy article relocations: Console-teleprompter, REST client, and string-interpolation tutorials remain in their current sections. They're intermediate content that doesn't fit the "finish in one day" Get Started scope.

Internal previews

Toggle expand/collapse

📄 File	🔗 Preview link
docs/csharp/index.yml	highlightedContent section (Optional; Remove if not applicable.)
docs/csharp/toc.yml	Taken from https://github.com/dotnet/roslyn/wiki/Samples-and-Walkthroughs
docs/csharp/tour-of-csharp/index.yml	"C# documentation"
docs/csharp/tour-of-csharp/overview.md	A tour of the C# language
docs/csharp/tour-of-csharp/strategy.md	Annotated C# strategy
docs/csharp/tour-of-csharp/tips-for-java-developers.md	docs/csharp/tour-of-csharp/tips-for-java-developers
docs/csharp/tour-of-csharp/tips-for-javascript-developers.md	Roadmap for JavaScript and TypeScript developers learning C#
docs/csharp/tour-of-csharp/tips-for-python-developers.md	Python
docs/csharp/tour-of-csharp/tutorials/branches-and-loops.md	Branches and loops - Introductory tutorial
docs/csharp/tour-of-csharp/tutorials/hello-world.md	customer intent: As an aspiring developer, I want to learn C#.
docs/csharp/tour-of-csharp/tutorials/index.md	docs/csharp/tour-of-csharp/tutorials/index
docs/csharp/tour-of-csharp/tutorials/list-collection.md	Tutorial: Learn to manage data collections using List<T> in C#
docs/csharp/tour-of-csharp/tutorials/numbers-in-csharp.md	Work with Numbers - Introductory tutorial
docs/csharp/tour-of-csharp/tutorials/pattern-matching.md	Tutorial: Use C# to match data against patterns
docs/csharp/tour-of-csharp/tutorials/tuples-and-types.md	docs/csharp/tour-of-csharp/tutorials/tuples-and-types
docs/csharp/tour-of-csharp/what-you-can-build.md	What you can build with C#

Copilot

Pull request overview

This PR modernizes the C# “Get started” experience by adding a new workloads overview article and adding clearer audience signposts plus “next steps” cross-links across the Tour of C# landing pages, overview article, tips-for-X roadmaps, and the interactive tutorial series.

Changes:

Adds a new “What you can build with C#” article and links it from the C# TOC and hub/landing pages.
Updates Tour of C# overview, landing page, and tutorials to include audience guidance plus expanded “Learn more”/“Next steps” navigation into Fundamentals.
Enriches tips-for-Java/JavaScript/Python articles with side-by-side syntax comparisons and adds consistent “Next steps” sections.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/csharp/tour-of-csharp/what-you-can-build.md	New workloads overview article with links into major .NET app types and next steps.
docs/csharp/tour-of-csharp/index.yml	Reshapes Tour of C# landing page to guide different audiences and surface the new workloads article.
docs/csharp/tour-of-csharp/overview.md	Adds audience guidance, reinforces file-based apps, and adds “Learn more” and “Next steps” links.
docs/csharp/tour-of-csharp/strategy.md	Adds audience guidance and links “workloads” mention to the new workloads article.
docs/csharp/tour-of-csharp/tips-for-java-developers.md	Adds intro, syntax comparisons, and next steps for Java developers.
docs/csharp/tour-of-csharp/tips-for-javascript-developers.md	Adds intro, TypeScript/C# comparisons, and next steps for JS/TS developers.
docs/csharp/tour-of-csharp/tips-for-python-developers.md	Adds intro, Python/C# comparisons, and next steps for Python developers.
docs/csharp/tour-of-csharp/tutorials/index.md	Adds audience guidance, clarifies file-based apps, and adds a “What’s next?” section.
docs/csharp/tour-of-csharp/tutorials/hello-world.md	Adds audience tip plus expanded Fundamentals-oriented “Next steps.”
docs/csharp/tour-of-csharp/tutorials/numbers-in-csharp.md	Adds audience tip, “Learn more” callouts, and expanded “Next steps.”
docs/csharp/tour-of-csharp/tutorials/tuples-and-types.md	Adds audience tip, “Learn more” callout, and expanded “Next steps.”
docs/csharp/tour-of-csharp/tutorials/branches-and-loops.md	Adds audience tip, “Learn more” callout, and expanded “Next steps.”
docs/csharp/tour-of-csharp/tutorials/list-collection.md	Adds audience tip, “Learn more” callout, and expanded “Next steps.”
docs/csharp/tour-of-csharp/tutorials/pattern-matching.md	Adds audience tip, “Learn more” callout, and expanded “Next steps.”
docs/csharp/toc.yml	Adds the new workloads article under “Get started.”
docs/csharp/index.yml	Updates the hub “Get started” card to include the new workloads article and a signpost to tips-for-X.

docs/csharp/index.yml

docs/csharp/tour-of-csharp/tutorials/list-collection.md

docs/csharp/tour-of-csharp/tutorials/numbers-in-csharp.md

docs/csharp/tour-of-csharp/tutorials/pattern-matching.md

docs/csharp/tour-of-csharp/what-you-can-build.md

Phase 2 is now complete.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docs/csharp/tour-of-csharp/what-you-can-build.md

meaghanlewis

Great improvements @BillWagner!

meaghanlewis · 2026-02-18T20:50:20Z

docs/csharp/tour-of-csharp/what-you-can-build.md

+- **[Azure AI services](/azure/ai-services/)** - Access pre-built AI capabilities like vision, language understanding, and speech recognition.
+- **[ML.NET](../../machine-learning/index.yml)** - Build custom machine learning models in C# without requiring deep ML expertise.
+
+Get started with [ML.NET tutorials](../../machine-learning/index.yml).


The rest of the sections all say Get started: rather than Get started with. For consistency, you can either update this line or update the others.

meaghanlewis · 2026-02-18T22:39:47Z

docs/csharp/tour-of-csharp/tutorials/pattern-matching.md

+
+You completed all the introductory tutorials! Here's where to go next:

+- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.


File-based apps or file-based programs? I see both uses in this PR but file-based apps more often.

meaghanlewis · 2026-02-18T22:41:27Z

docs/csharp/tour-of-csharp/tutorials/pattern-matching.md

+
+You completed all the introductory tutorials! Here's where to go next:

+- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.


Suggested change

- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.

- [File-based apps](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.

meaghanlewis · 2026-02-18T22:42:04Z

docs/csharp/tour-of-csharp/tutorials/hello-world.md

+
+- [Strings](../../programming-guide/strings/index.md) — Learn more about the `string` type you used in this tutorial.
+- [Methods and program structure](../../fundamentals/program-structure/index.md) — Understand how C# programs are organized.
+- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used to run your code.


Suggested change

- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used to run your code.

- [File-based apps](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used to run your code.

dotnetrepoman bot added this to the February 2026 milestone Feb 9, 2026

dotnet-policy-service bot added dotnet-csharp/svc get-started/subsvc okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings. labels Feb 9, 2026

BillWagner marked this pull request as ready for review February 9, 2026 21:02

BillWagner requested a review from a team as a code owner February 9, 2026 21:02

Copilot AI review requested due to automatic review settings February 9, 2026 21:02

Copilot started reviewing on behalf of BillWagner February 9, 2026 21:03 View session

Copilot AI reviewed Feb 9, 2026

View reviewed changes

BillWagner marked this pull request as draft February 10, 2026 15:34

BillWagner added 20 commits February 11, 2026 11:48

Complete phase 1

8e2f75f

Finish step 3.

0d04992

Finish step 4

374a757

Phase 2 is now complete.

Finish step 5.

beb7f8d

Content edit

7143091

Continue to step 6.

cfef159

Finish step 7.

01ad867

copy edit

6a61c9b

Complete step 8

1c291e1

copy edit.

75ee0a2

Finish step 9

f69a61b

copy edit

f6675ac

Step 10 for the plan.

64ccd52

copy edit

2c5be0b

update tutorial

3a7899a

Refresh first tutorial.

f2ad32f

refresh numbers tutorial

bae85a8

copyedit

6e12ad8

Refresh this article.

68de7e6

copy edit on tuples-and-types

4a7862e

BillWagner added 9 commits February 11, 2026 11:48

copy edit

2ccc085

refresh this tutorial

cd3b112

copy edit

23ec088

refresh patterns tutorials

11f7f91

Finish the final tutorial

fc9f639

Update links and checks

1d79447

fix warnings

b5eba32

Add links to Aspire

4dbd023

interim checkin.

9f64d52

BillWagner force-pushed the get-started-modernization branch from 20b2b79 to 9f64d52 Compare February 11, 2026 16:48

BillWagner and others added 3 commits February 13, 2026 15:44

Apply suggestions from code review

6ef463a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

General Copyedit.

e4bec66

small nits

c2de9bb

BillWagner marked this pull request as ready for review February 17, 2026 20:41

BillWagner commented Feb 17, 2026

View reviewed changes

docs/csharp/tour-of-csharp/what-you-can-build.md Outdated Show resolved Hide resolved

Apply suggestion from @BillWagner

38bdef0

meaghanlewis approved these changes Feb 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modernize the Get Started content#51565

Modernize the Get Started content#51565
BillWagner wants to merge 33 commits intodotnet:mainfrom
BillWagner:get-started-modernization

BillWagner commented Feb 9, 2026 •

edited by github-actions bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

meaghanlewis left a comment

Uh oh!

meaghanlewis Feb 18, 2026

Uh oh!

meaghanlewis Feb 18, 2026

Uh oh!

meaghanlewis Feb 18, 2026

Uh oh!

meaghanlewis Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments


		You completed all the introductory tutorials! Here's where to go next:

		- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.

	- [File-based programs](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.
	- [File-based apps](../../fundamentals/tutorials/file-based-programs.md) — Learn about the `dotnet run` command you used throughout these tutorials.

Conversation

BillWagner commented Feb 9, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Phase 1 — New content

Phase 2 — Reshape landing/hub pages

Phase 3 — Update Tour of C# articles

Phase 4 — Update tutorials

Phase 5 — TOC updates

Phase 6 — Verify no legacy articles should move

Verification

Decisions

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

meaghanlewis left a comment

Choose a reason for hiding this comment

Uh oh!

meaghanlewis Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

meaghanlewis Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

meaghanlewis Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

meaghanlewis Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

BillWagner commented Feb 9, 2026 •

edited by github-actions bot

Loading