Proposal: Comprehensive PowerShell 5.1 to 7.x migration guide (7 new articles)

[SufficientDaikon]

Summary

The current migration doc (Migrating from Windows PowerShell 5.1 to PowerShell 7)
is a feature overview, not a migration guide. It tells readers what PowerShell 7 offers
but not how to migrate. The differences doc is a thorough technical reference,
but it is not actionable — it lists what changed without explaining what to do about it.

This proposal restructures the migration story into a hub-and-spoke model:

• Rewrite the existing migration doc as a phased playbook (assess → install → migrate → validate)
• Add 7 new deep-dive articles covering the top community pain points
• Link to the existing differences doc for technical reference (no duplication)

Pain points covered (with issue evidence)

Every proposed article addresses real pain points backed by community issue data:

Pain point	Evidence (PowerShell/PowerShell)	Proposed article
Module compatibility confusion	#4062 (63 comments), #15428 (33 comments)	module-compatibility-strategy.md
PSModulePath + OneDrive conflicts	#15552 (109 comments)	module-compatibility-strategy.md
Encoding changes (UTF-8 NoBOM)	#1995 (201 comments), #707 (22 comments)	encoding-changes.md
Remoting endpoint defaults to WinPS	#11616 (32 comments)	Hub article (Phase 4)
Air-gapped network slow startup	#10983 (58 comments)	enterprise-deployment.md
Profile path differences	#4682	profile-migration.md
Removed cmdlets/features (WMI, Workflow, EventLog)	Referenced in differences doc	script-compatibility-audit.md
Task Scheduler / PSScheduledJob removal	Referenced in differences doc	scheduled-tasks-automation.md

Proposed file structure

whats-new/
  Migrating-from-Windows-PowerShell-51-to-PowerShell-7.md  ← rewritten as phased playbook
  migration/
    script-compatibility-audit.md      (~400 lines)
    module-compatibility-strategy.md   (~350 lines)
    encoding-changes.md                (~350 lines)
    profile-migration.md               (~250 lines)
    enterprise-deployment.md           (~350 lines)
    scheduled-tasks-automation.md      (~250 lines)
    testing-and-rollback.md            (~250 lines)

Updates to existing files (cross-links only):

• differences-from-windows-powershell.md — NOTE box linking to migration guide
• module-compatibility.md — expanded "Finding the status" section + link to new article
• toc.yml — migration subsection under "What's New"
• overview.yml — migration card on landing page

Total: 15 files, ~2,700 lines new content (within the 50-file limit)

Design principles

1. Hub-and-spoke: the rewritten migration doc links to deep-dives, never duplicates
2. Actionable: every section has concrete steps, scripts, or checklists
3. Issue-backed: every pain point references real GitHub issues
4. Non-duplicating: spoke articles link to specific ## anchors in the differences doc
5. Style-compliant: 100-char lines, ATX headers, backtick fences, dash lists, proper name capitalization

Questions for maintainers

1. Directory location: Is whats-new/migration/ the right place for the new articles,
   or would you prefer flat files in whats-new/ with a migration- prefix?

2. TOC structure: Should migration be a subsection under "What's New in PowerShell",
   or elevated to its own top-level section in the TOC?

3. TOC modification: Is it acceptable for a community PR to modify toc.yml,
   or should maintainers handle TOC changes after merge?

Prior contribution context

I recently contributed PR #12890 (+2,800/-278 across 30 files) which overhauled the
error handling documentation. This proposal is a similar scope and follows the same
quality standards.

---