Getting Started UX Improvements

kristenwomack commented 4 months ago

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 and azd - 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.
[ ] #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 before azd up
[ ] Consider adding instructions at the end of the installation success message to run azd auth login
[ ] https://github.com/Azure/azure-dev/issues/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.

[ ] Add CI/CD pipeline setup as a sub-page or as a Next Step

Learn Modules

[ ] Refactor Learn modules with repetitive content (page 30 in reference file, link below): example scenario, how to install azd, typical azd 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

cc: @gkulin @SophCarp @Austinauth

SophCarp commented 4 months ago

Related item: https://github.com/rnd-pm-ux-design-amandas/d3-devex-work-items/issues/716 Design experience audit

Austinauth commented 3 months ago

Please see #3964 for template list improvements.

Azure / azure-dev