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/fundamentals/tutorials/file-based-programs.md	Tutorial: Build file-based C# programs
docs/csharp/index.yml	highlightedContent section (Optional; Remove if not applicable.)
docs/csharp/language-reference/compiler-messages/preprocessor-errors.md	Preprocessor errors and warnings
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.

[meaghanlewis]

Great improvements @BillWagner!

[meaghanlewis]

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