Minor changes for simplified init experience for 9/6

[savannahostrowski]

Updated by Austin A on 08/31/2023

azd init changes

1. "Select a template" misinterpreted

Owner: @gkulin to review prompt and suggest alternative language to help clarify.
Status: In review (issue comment below)

Problem

"Select a template" misinterpreted by multiple customers as choosing a template that will then be applied to your current app, and refactor your code to fit that template.

Solution

TBD

---

2. Missing "no code detected" error message

Owner: @Austinauth
Status: ✅ Design complete / 🚨 Ready for Dev

Problem

When a user scans the code in their current directory but no code exists we show them an empty detection summary.

Solution

Add the following error message when a user opts to Use code in current directory but no code is found:

Error: No files or services detected in the current directory.

Ensure you’re in the directory where your app code is located and try again. If you do not have code and would like to start with an app template run 'azd init' in an empty directory and select the option to Use a template.

For more information, refer to the documentation or run 'azd help'.

---

3. The word "services" in "add or remove services" is unclear

Owner: @weikanglim
Status: ✅ Dev complete

Problem

The word "services" in "add or remove a service" is unclear, causing some customers to believe it is talking about modifying Azure services, rather than confirming that the detection worked accurately.

Solution

Add the word "detected" to action to draw an even stronger connection to the detection summary.

Add or remove a detected service

---

4. "Database name" misinterpreted as being any name

Owner: @gkulin
Status: In review (issue comment below)

Problem

'database name' misinterpreted as being any name, rather than the database name that the application expects. Multiple customers believed that they can provide any name to the database. Although we have help text, and see the help text pattern working well for environment name, for the database name no customer has used the help pattern for some reason (maybe they have a stronger conviction that they know what 'database name' is?).

Solution

TBD

---

5. [Bug] Help text disappears

Owner: @Austinauth
Status: ✅ Design complete / 🚨 Ready for Dev

Problem

Help text disappears for many users once they've moved on to the next prompt.

Solution

Help text should stay visible once the user has moved to the next prompt.

---

6. [Bug] Loading animation breaks at times due to hooks

Owner: N/A
Status: 🚨 Awaiting dev

Problem

Loading animation breaks due to the hooks.

---

7. Escape sequence needed during troubleshooting steps

Owner: @Austinauth
Status: ✅ Design complete / 🚨 Ready for Dev

Problem

User is locked into troubleshooting path.

Solution

Provide option for the user to "cancel" or "go back" if they decide not to continue troubleshooting.

Cancel from service add

Cancel from path input

---

next-steps.md changes

8. Make relationship between ‘azd up,’ ‘azd provision,’ and ‘azd deploy’ more clear.

Owner: @gkulin
Status: ✅ Dev complete

Problem

The line which talks about the relationship between ‘azd up’ and ‘azd provision’ and ‘azd deploy’ – multiple customers questioned whether ‘up’ included ‘provision’ and ‘deploy’ commands, or if they needed to be run in succession.

9. Re-work heading levels to follow a logical "Chapter in a book" model.

Owner: @gkulin
Status: ✅ Dev complete

Problem

Per Florian's feedback, Headings should act as chapters in a book where H1 is the title, H2s are chapters (e.g. 1, 2), and H3s are sub-chapters within those (e.g. 1.2, 1.3). Suggestions include:
Make Troubleshooting, Billing, What was Added their own chapters so they are more easily discoverable, not hidden under details.
Make Next Steps a high level chapter with "define environment variables" and "Provision infrastructure and deploy application code" sub-chapters of that.
Fix Troubleshooting list items - currently all 1s.

10. Explain that buildpacks are being used if you don't have a dockerfile

Owner: @gkulin
Status: ✅ Dev complete

Problem

One customer who understood that her app was being containerized looked for a dockerfile added to her app, but did not find one. Neither the CLI output nor next-steps clearly mentions the use of buildpacks. In the real world, this customer would have no way to understand that we are using buildpacks.

Additionally, in package step, have a message like "no dockerfile found, using buildpacks..." Either explain in line or link out to docs.

[gkulin]

I'm giving a couple options for each copy fix so please feel free to voice your opinions!

1 - "Select a template" is misinterpreted
alternatives:

• Start with a new template (recommended for empty directory only)
• Create new app, beginning from a template (recommended for empty directory)
• Create new app, with a template

2 - "database name" is misinterpreted
alternatives:

• Input the ([DB Type]) database name used in your app
• Input the name of the database ([DB Type]) as it is used in your app

I also want to note here that the help text for the database name also might lead users to believe that the database name can be anything

[savannahostrowski]

@gkulin Have you considered "Initialize your application from a template" for "select a template"

For 2, I'd probably vote for "Input the name of the database ([DB Type]) as it is used in your app". I recognize that it's longer but I do think it's clearer.

[Austinauth]

A few notes:

• I've updated @savannahostrowski's initial message above with the list of remaining items, the solution owner, and the status. Please make an effort to update the list when a solution is decided for a given item (cc: @gkulin)
• Only items missing from the list are things we decided could wait until post release as well as items related to the next-steps.md file. @Irina If there's anything for the 9/6 release related to this can you add? I didn't have a chance to capture them during the meeting yesterday.
• @gkulin will provide feedback for you by EoD!
• @weikanglim let me know if you'd prefer that I file the two bugs as separate issues

[Austinauth]

@gkulin @savannahostrowski @weikanglim

Re: Missing no code detected error message

Thoughts on either of these error messages? Content, layout, etc.

I'm leaning option 2 for the succinctness of it.

[gkulin]

Have you considered "Initialize your application from a template" for "select a template"

@savannahostrowski I did think about something like that but thought that some people still might think that means the template will be applied to your current app and refactor the code to fit the template

what do you think of "Initialize a new application from a template"?

[gkulin]

@Austinauth I like option 2! Is 'documentation' a clickable link?

[Austinauth]

I'm giving a couple options for each copy fix so please feel free to voice your opinions!

1 - "Select a template" is misinterpreted alternatives:

• Start with a new template (recommended for empty directory only)
• Create new app, beginning from a template (recommended for empty directory)
• Create new app, with a template

2 - "database name" is misinterpreted alternatives:

• Input the ([DB Type]) database name used in your app
• Input the name of the database ([DB Type]) as it is used in your app

I also want to note here that the help text for the database name also might lead users to believe that the database name can be anything

Re: 1

Still not sure I am in love with any of these options. I think the missing element for me is the inference that you will be selecting the template. It's not something that you have to provide.

Re: 2

I like the second option: Input the name of the database ([DB Type]) as it is used in your app

Re: DB Hint

Agree about the DB name hint text. The first line could probably be revised to be a more detailed version of the prompt.

Something like:

Input the name of your database as it is defined in your application files (case sensitive). If you do not input the name of your database exactly as it is defined [x] will happen...

Also wonder if showing the examples here actually adds confusion. Its the first thing your eyes land on and it could give the impression that you can name the DB anything as long as it follows the format of the examples.

[Austinauth]

@Austinauth I like option 2! Is 'documentation' a clickable link?

Ideally! We just have to get this issue resolved first for it to work: #2539

[irinasmoke]

next-steps.md changes

Make relationship between ‘azd up,’ ‘azd provision,’ and ‘azd deploy’ more clear.

The line which talks about the relationship between ‘azd up’ and ‘azd provision’ and ‘azd deploy’ – multiple customers questioned whether ‘up’ included ‘provision’ and ‘deploy’ commands, or if they needed to be run in succession.

Re-work heading levels to follow a logical "Chapter in a book" model.

Per Florian's feedback, Headings should act as chapters in a book where H1 is the title, H2s are chapters (e.g. 1, 2), and H3s are sub-chapters within those (e.g. 1.2, 1.3). Suggestions include:
Make Troubleshooting, Billing, What was Added their own chapters so they are more easily discoverable, not hidden under details.
Make Next Steps a high level chapter with "define environment variables" and "Provision infrastructure and deploy application code" sub-chapters of that.
Fix Troubleshooting list items - currently all 1s.

Explain that buildpacks are being used if you don't have a dockerfile

One customer who understood that her app was being containerized looked for a dockerfile added to her app, but did not find one. Neither the CLI output nor next-steps clearly mentions the use of buildpacks. In the real world, this customer would have no way to understand that we are using buildpacks.

Additionally, in package step, have a message like "no dockerfile found, using buildpacks..." Either explain in line or link out to docs.

[gkulin]

next-steps.md changes

I made these changes here: weikanglim/scaffold-projects#2

[Austinauth]

Thank you @gkulin!

Status of all the items in the initial issue comment are now up to date.