azd help improvements

[savannahostrowski]

Should we group the commands by task?

[jongio]

Yes!

[Austinauth]

@savannahostrowski As we discussed earlier, let's make the #663 issue an Epic and this issue a task within the epic (I'm not sure how to do that myself).

[savannahostrowski]

Moving this to November (later half of the month)

[Austinauth]

Update 10/25/2022

• Begin work on this week of 11/14

[puicchan]

New command azd config is available since release azure-dev-cli_0.4.0-beta.1. Please make sure you include azd config in your exploration.

[Austinauth]

Proposed --help templates I shared today on the demo.

General Help (azd --help)

Command Help (azd [command] --help)

[Austinauth]

Update 01/16/2022

• Finalized designs for 12 different azd help experiences
• Presented to team on azd Demo playback
• Detailed feedback provided by @savannahostrowski, @gkulin, @ellismg and Crystal Barragan
• Ready for implementation discussions (cc: @rajeshkamal5050 , @savannahostrowski)

Overview of new designs

Prototype featuring the proposed azd help and azd <command> --help designs can be found here. Use < and > arrows to toggle through pages.

Summary of changes and features

• Overhauled the layout, hierarchy and visual design of both general and command specific help to be more scannable, and to align with the design language we are establishing for the rest of the CLI (consistency).
• Commands regrouped to more accurately reflect the jobs a user can complete using the CLI.
• Reworked individual descriptions for commands, flags and global flags to be more clear.
• Reworked intro descriptions to be more succinct (introduced bullet point format).
• Introduced an examples section for most commands to aid in understanding.
• Introduced new convenience commands/flags: docs, --docs, upgrade. Needs team approval.

Links to individual help experiences

• azd help
• azd up --help
• azd down --help
• azd init --help
• azd provision --help
• azd deploy --help
• azd env --help
• azd config --help
• azd restore --help
• azd pipeline --help
• azd monitor --help
• azd template --help

---

Any feedback on the design is still gladly accepted!

[savannahostrowski]

@rajeshkamal5050 This is ready for implementation in 0.7. Please let @Austinauth Austin know if anything else is needed!

[rajeshkamal5050]

@savannahostrowski @Austinauth
 
Some comments
• Grouping description changes
• Moved deploy into the 2nd bucket
• Put monitor, test and release together
• Moved login/logout onto the first bucket. For downloading/initializing and developing apps localy. We need authentication.

• Setup, configure and develop your app
  -- config
  -- init
  -- restore
  -- template
  -- login
  -- logout
   
• Manage azure resources and app deployments
  -- deploy
  -- down
  -- env
  -- infra
  -- up
   
• Monitor, test and release your app
  -- monitor
  -- pipeline
   
• About, help and upgrade
  -- docs
  -- help
  -- upgrade
  -- version

[Austinauth]

@savannahostrowski are you good with Rajesh proposed tweaks? I don't have any issues.

[Austinauth]

@rajeshkamal5050 I spoke with @savannahostrowski regarding the suggested changes.

We're mostly good on them except:

Setup, configure and develop your app

Setup and configure are a little redundant, will just use configure for now if that's okay?

I should have the prototype updated by the time you read this message.

[rajeshkamal5050]

@Austinauth sounds good.