Modernize the Get Started content

[BillWagner]

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

1. 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.

2. 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

3. 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.

4. 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

5. 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.

6. 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.

7. 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.

8. 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.

9. 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

10. 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.

11. 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

12. 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

13. 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.

[Copilot]

This link text says it’s for Java, JavaScript, and Python developers, but it points to the Java-only roadmap article. Either change the text to match the destination, or link to a page/section that actually aggregates the three roadmaps.

Suggested change

	text: "C# for Java, JavaScript, and Python developers"
	text: "C# for Java developers"

[Copilot]

The markdownlint directive is disabled twice; the second one should be an enable (or be removed) so MD033 gets re-enabled after the

Details

block. Leaving it disabled can mask unrelated lint issues later in the file.

Suggested change

	<!-- markdownlint-disable MD033 -->
	<!-- markdownlint-enable MD033 -->

[Copilot]

In this “Next steps” list, “The C# type system” and “Numeric types in C# Fundamentals” both link to the same Fundamentals type-system page. De-duplicate these entries, or update the “Numeric types…” link to a more specific target if one exists.

Suggested change

- [Numeric types in C# Fundamentals](../../fundamentals/types/index.md) — Understand how C# represents numbers in the type system.

[Copilot]

There’s a double space before “Let’s start to explore…” after the Nullable value types link. Remove the extra space to avoid awkward rendering and keep spacing consistent.

Suggested change

The preceding tutorials demonstrated built-in types and types you define as tuples or records. You can check instances of these types against a *pattern*. Whether an instance matches a pattern determines the actions your program takes. In the examples that follow, you see `?` after type names. This symbol allows the value of this type to be null (for example, `bool?` can be `true`, `false`, or `null`). For more information, see [Nullable value types](../../language-reference/builtin-types/nullable-value-types.md). Let's start to explore how you can use patterns.

The preceding tutorials demonstrated built-in types and types you define as tuples or records. You can check instances of these types against a *pattern*. Whether an instance matches a pattern determines the actions your program takes. In the examples that follow, you see `?` after type names. This symbol allows the value of this type to be null (for example, `bool?` can be `true`, `false`, or `null`). For more information, see [Nullable value types](../../language-reference/builtin-types/nullable-value-types.md). Let's start to explore how you can use patterns.

[Copilot]

The PR description’s Verification section says “Confirm all edited files have ms.date: 02/06/2026,” but several updated files (including this one) use 02/09/2026. Update the PR description (or the dates) so the checklist matches what the PR is actually doing.

[Copilot]

The Desktop section implies macOS support for all the listed UI stacks, but WPF and Windows Forms are Windows-only. Reword this section to avoid suggesting those frameworks run on macOS (for example, call out MAUI as cross-platform and WPF/WinForms as Windows-only).

Suggested change

	C# supports building desktop applications for Windows and macOS:
	- **[.NET MAUI](/dotnet/maui/)** creates cross-platform desktop apps that run on Windows, macOS, Android, and iOS from a single codebase.
	- **[Windows Presentation Foundation (WPF)](/dotnet/desktop/wpf/)** builds rich Windows desktop apps with advanced graphics and data binding.
	- **[Windows Forms](/dotnet/desktop/winforms/)** provides a straightforward way to create Windows desktop apps with a visual designer.
	Use C# to build Windows desktop apps, and cross-platform desktop apps that run on Windows and macOS:
	- **[.NET MAUI](/dotnet/maui/)** creates cross-platform desktop apps that run on Windows, macOS, Android, and iOS from a single codebase.
	- **[Windows Presentation Foundation (WPF)](/dotnet/desktop/wpf/)** builds rich Windows-only desktop apps with advanced graphics and data binding.
	- **[Windows Forms](/dotnet/desktop/winforms/)** provides a straightforward way to create Windows-only desktop apps with a visual designer.