Add a migration best practices guide

[joeduffy]

No description provided.

[claude]

Documentation Review

I've reviewed PR #16646 which adds a comprehensive migration best practices guide. Overall, this is excellent documentation that fills an important gap in the migration journey. The content is well-structured, practical, and actionable.

Issues Found

Broken Links

Line 14 (best-practices.md):
The link to /docs/iac/guides/migration/converters/ appears to be incorrect. The actual file is at /docs/iac/guides/migration/converters.md (no subdirectory). The link should be:

Pulumi's migration tools ([converters](/docs/iac/guides/migration/converters/), [`pulumi import`](/docs/iac/cli/commands/pulumi_import/), and the [`import` resource option](/docs/iac/concepts/resources/options/import/)) provide powerful building blocks for bringing existing infrastructure under Pulumi's management. However, real-world migrations involve challenges that go beyond running a single command.

Wait - actually, I need to verify this is a Hugo-style trailing slash link, which should work. Let me note it as something to verify during build.

Lines 464, 491 (best-practices.md):
Links to /docs/iac/guides/ai-integration/mcp-server/ are correct - the file exists at content/docs/iac/guides/ai-integration/mcp-server/index.md.

Lines 487-489 (best-practices.md):
Links to migration guides look correct based on the file structure.

Style Issues

Line 337 (best-practices.md):
The word "just" appears in the phrase "properties that just restate defaults." While the style guide discourages "just" as a minimizing word in general, this usage is acceptable in context as it means "merely" or "only." No change needed.

Positive Observations

✅ Front matter is complete with proper title, meta_desc, h1, and menu configuration
✅ File ends with newline as required
✅ Headings follow proper hierarchy - H2 for main sections, H3 for subsections, no skipped levels
✅ Heading capitalization follows style guide - sentence case for H2+
✅ Code blocks properly use fenced blocks with language tags (bash, typescript, output)
✅ Tables are well-formatted and provide clear reference information
✅ Internal links use descriptive text, not "click here" or "here"
✅ Link paths follow Hugo conventions with trailing slashes
✅ Spelling and grammar are correct throughout
✅ Ordered lists properly use 1. for all items
✅ Technical accuracy - commands, syntax, and guidance are correct
✅ Inclusive language - no problematic terms found

Content Quality

The guide excels at:

• Practical focus: Real-world scenarios and solutions, not just theory
• Clear structure: Logical progression from planning through execution to troubleshooting
• Actionable examples: Concrete code samples and command-line examples
• Troubleshooting section: Anticipates common issues and provides solutions
• Integration: Properly references Neo and MCP Server for AI-assisted migrations
• Cross-references: Links to related documentation for deeper dives

Minor Recommendations

Consider these enhancements (not blocking):

1. Example import commands: The "Finding resource IDs" section shows how to get IDs but could include one complete pulumi import example combining ID + type token
2. Preview diff example: Section on "Achieving a clean preview" could show what a diff actually looks like
3. Common ID format mistakes: The ID format reference table is helpful - consider adding a "Common Mistakes" column

Verification Needed

During make build, verify that all internal links resolve correctly, particularly:

• /docs/iac/guides/migration/converters/
• /docs/iac/cli/commands/pulumi_import/

Hugo's link checking should catch any 404s.

---

This is high-quality documentation that will significantly help users navigate the migration journey. The practical, real-world focus is exactly what's needed.

@claude if you'd like me to review any revisions or provide additional feedback on specific sections.

[pulumi-bot]

Your site preview for commit dea2d94 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16646-dea2d940.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit 114cf61 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16646-114cf61d.s3-website.us-west-2.amazonaws.com.