Docs TOC remodel

[kristenwomack]

We are remodeling the docs TOC for azd. The goal is to make using azd clearer, especially in the flow of getting started and progressing to a day n tool for developers pushing changes to production.

[kristenwomack]

Proposal

Introduction and overview

• Azure Developer CLI overview
• What is Azure Developer CLI?
• Supported languages and environments

Getting started

• Install or update azd
• Quickstarts
  • Deploy your first template (CLI)
  • Explore a sample template (Codespaces - new next step doc)
  • Use the azd Visual Studio Code Extension
• Explore azd template galleries (New doc to highlight these better)

Core concepts

• Azure Developer CLI vs Azure CLI
• CLI commands overview
• Templates overview
• azure.yaml overview
• The azd init workflow
• The azd up workflow
• Feature versioning and release strategy

Development workflows

• Get started with template development
• Use azd compose
  • What is azd compose?
  • Build a template using compose
  • Generate Bicep using compose
• Build a template
  • Start from existing app code
  • Start from an existing template
  • Training - build and deploy azd templates

Deployment and operations (provisioning? naming TBD?)

• Deployment concepts & strategies (new intro overview of some sort?)
• Use Terraform or Bicep as IaC provider
• Continuous Integration/Continuous Deployment (CI/CD)
  • Integrate with GitHub Actions
  • Integrate with Azure Pipelines
• Monitoring and Logging
  • Enable monitoring (pointer to Azure products for monitoring your app)
  • Enable verbose mode
  • Follow error to Azure logs
• Deployment configuration
  • Subscription and resource group scoped deployments
  • Use third-party container registries
  • Use helm & kustomize
  • Configure service packaging ignore files
  • Use Azure deployment stacks
  • Deploy to Azure AI/ML online endpoints
• Work with environments
  • Understand azd environments
  • Work with environment variables
  • Environment variables FAQ
  • Remote Environment Support
  • Azure Deployment Environments integration
• .NET Aspire support
  • .NET Aspire integration and deployment
  • Deploy .NET Aspire apps using pipelines

Configuration

• Manage config settings
• Configure template sources
• Enable demo mode
• Configure service packaging ignore files
• Use azd in sovereign clouds

Advanced usage (some of these are future docs)

• Customize workflows using command and event hooks
• Work with azd extensions
• Custom Commands
• Scripting and Automation
• Performance Optimization

Security and recommended practices (future docs)

• Managed identity
• Key vault

Troubleshoot

• Troubleshoot common issues
• Handle PowerShell errors
• Enable logging
• Pipeline config for CI/CD

Reference & resources

• Frequently asked questions
• Command reference
• azure.yaml schema reference
• News and blog posts
• Release blog posts
• CDN changes
• Glossary

[fiveisprime]

The Azure Extensions could fit nicely into the "Deployment and operations" section. Checking and managing state (stop/start), egress, environment variables, stuff like that. @mistymadonna

[vhvb1989]

I love this.
I think this new structure will allow us to find a place for the docs we currently have in: https://github.com/Azure/azure-dev/tree/main/cli/azd/docs

[kristenwomack]

Internal feedback from Pamela: generally looks good, but wondering where host-specific guidance would go - how to build a template for ACA (especially), but also functions, app service, etc. [this is in the works]

[kristenwomack]

Need doc to cover azd extension in VS Code.

[kristenwomack]

New TOC is live https://aka.ms/azd