Description
This is an epic level issue organizing all of the findings and actions we plan to take from the Getting Started with azd Study.
Understanding the Azure Developer CLI (azd
)
- There is confusion between
az
andazd
- create a strategy and tactical ways we can help delineate between the tool so customers know what tool will help with the task or JTBD for their scenario. We may consider explanations, SEO improvements, adding clarity in our docs or FAQs section, etc. We may also consider changing the name. - Create azd videos for getting started #4178
Installing azd
- Consider changing option from OS to shell since the shells are less tightly coupled today (Windows + Bash, or OSX + PowerShell, or using the terminal in VS Code)
Finding a template (docs or azd template list
)
azd template list
output is overwhelming
- JTBD: find a template that most closely matches my use case. How to filter the list on their criteria? How will developers know they've found the template they need (based on title alone)?
- JTBD: find a specific template. Search capability? Then pass that template to
azd init
- See other considerations in the reference document
- Add clarity for how
azd
works without templates - Language consistency: "template" and "project" are used interchangeably in our docs and learn modules today
- Highlight extensible nature of azd templates more throughout the docs
- Point to "Make your project azd-compatible" earlier / more clearly. Currently, the file is in a section called "Create templates" -- consider changing to "Use azd with existing application code"
Initializing my project (azd init
)
Several participants ran init
in a non-empty directory and were surprised when the template files scattered among their existing files (vs than in a contained folder). "Would have preferred if it went into a folder kind of like how GitHub does when you clone things."
- Consider having
azd init
create a new folder (named after the template?) containing the template files
Deploying my app (azd up
)
45% of participants failed running azd up
for the first time because they were not logged in. The participants that succeeded were either following the Learn Modules or template's README (both have an explicit azd auth login
step.
- Add
azd auth login
step in docs beforeazd up
- Consider adding instructions at the end of the installation success message to run
azd auth login
- Call
azd login
for the user if they invoke anazd
command and are not authenticated #1391
azd up
takes a long time
About 1/3 of participants made a comment that azd up
took longer than they would expect; azd up
took over 10 minutes to complete for 4 out of 9 participants
- Consider using a different template as the go-to for Getting Started as a guide (8 of 9 participants used the first template suggested in the quickstart:
todo-nodejs-mongo
Participants noticed a disconnect between deployment status in the Azure Portal versus azd
. Developers said they want to trust the status in the Azure Portal over the command line. There is no clear suggestion here at the moment.
Running my app on Azure
Participants had trouble finding their app's endpoint in the azd deploy
output
3 of 9 participants went to the Azure Portal looking for their endpoint. All of them followed the last link in the terminal output taking them to the Resource Group.
- Explore restructuring the end of the
azd deploy
to put the endpoint links at the end.
- Some participants had to wait for their app's endpoint to load; consider a different template as the go-to for Getting Started; consider adding a note in docs that the endpoint might take a moment to load after deployment succeeds.
Set up a pipeline (azd pipeline config
)
Successfully setting up their pipeline easily and quickly was a wow moment for the participants that tried this step. The training module includes a unit for configuring CI/CD, but the quick start does not.
Learn Modules
- Refactor Learn modules with repetitive content (page 30 in reference file, link below): example scenario, how to install
azd
, typicalazd
workflow
General improvements to consider:
- Include the cost of what you are deploying or pointers to Azure calculators / references
- More guidance on how to use
azd
when you aren't starting from zero - Add documentation on setting up multiple environments (dev, test, stage, etc)
- Add pointers to additional Azure services they might want to use/add to a particular solution
Reference file: https://microsoft-my.sharepoint.com/:p:/p/gracekulin/EdVo163lJ-ZOulRALX4b_NUBAAksQ6uShQ2LyQHzDpyMFg?e=4OVjuC