Skip to content

Optimize ACA deployment docs workflow and content structure #3848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Jun 18, 2025

This PR restructures the Azure Container Apps (ACA) deployment documentation to optimize the workflow and content as requested in the issue. The changes focus on streamlining the user experience while maintaining comprehensive coverage for different deployment scenarios.

Key Changes

✅ Added Missing Functionality

  • New document: customize-deployments.md - Comprehensive guide for azd infra synth with production considerations
  • Covers infrastructure synthesis, security configurations, resource sizing, and advanced customization patterns
  • Includes best practices for production deployments and iterative workflows

✅ Removed Complex Manual Steps

  • Deleted unused include files: aca-bicep-cli-shared-steps.md (119 lines) and aca-configure-post-deployment.md (78 lines)
  • These contained extensive manual Azure CLI and Bicep steps that were not referenced by any documentation
  • Simplified deployment workflow by focusing on tool-assisted approaches

✅ Enhanced Content Organization

  • Updated main deployment guide to reference new customization document instead of vague CLI/Bicep mentions
  • Added cross-reference from in-depth guide to new customization document for production scenarios
  • Updated Visual Studio deployment description to be more accurate
  • Enhanced table of contents with proper placement and search keywords

✅ Maintained Existing Guides

  • azd deployment (aca-deployment.md) - Simple, quick deployment path
  • Visual Studio deployment (aca-deployment-visual-studio.md) - IDE-integrated experience
  • CI/CD deployment (aca-deployment-github-actions.md) - GitHub Actions and Azure DevOps pipelines
  • In-depth guide (aca-deployment-azd-in-depth.md) - Deep dive into azd internals

Documentation Structure Now Provides

  1. Clear progression: Simple → Advanced → Production customization
  2. Focused content: Each document has a specific, well-defined purpose
  3. Reduced complexity: Eliminated confusing manual workflows in favor of tool-guided approaches
  4. Complete coverage: From getting started to production-ready deployments

Validation

✅ All markdown files pass linting
✅ Links verified and working
✅ Content follows Microsoft Writing Style Guide
✅ Cross-references properly connect related topics

This addresses the original concern about "extensive number of steps for Bicep and the CLI" by removing complex manual workflows and replacing them with focused, tool-specific guidance that scales from development to production.

Fixes #404.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.


Internal previews

📄 File 🔗 Preview link
docs/deployment/azure/aca-deployment-azd-in-depth.md docs/deployment/azure/aca-deployment-azd-in-depth
docs/deployment/azure/aca-deployment-visual-studio.md docs/deployment/azure/aca-deployment-visual-studio
docs/deployment/azure/aca-deployment.md docs/deployment/azure/aca-deployment
docs/deployment/azure/customize-deployments.md docs/deployment/azure/customize-deployments
docs/toc.yml docs/toc

…clude files

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
@Copilot Copilot AI changed the title [WIP] Revisit the ACA deployment docs to optimize the workflow and content Optimize ACA deployment docs workflow and content structure Jun 18, 2025
@Copilot Copilot AI requested a review from IEvangelist June 18, 2025 16:46
Copilot finished work on behalf of IEvangelist June 18, 2025 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Revisit the ACA deployment docs to optimize the workflow and content
2 participants