-
-
Notifications
You must be signed in to change notification settings - Fork 157
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve CLI UI and UX #872
Comments
@fmvilas Would love to work on this too. |
@fmvilas I would like to work on this one |
Bounty Issue's End Of Life (EOL): 2024-02-29 23:59:59 UTC-12:00 |
Hello @fmvilas Thank you. |
Since this is purely a design task (no code required), I'm assigning this to @Mayaleeeee. That said, we'll want to make it a reality down the track. As an outcome of this issue, Maya will come up with a list of other issues for implementation. Most likely good first issues. I count on you for those, @sambhavgupta0705 and @Shurtu-gal 🙏 |
Bounty Issue's Timeline
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better. |
Absolutely. Would be happy to work on them. I guess this can also be included in the v1 release tasks when @Mayaleeeee is done with it. |
Thanks, @fmvilas |
I've been told every issue on the Bounty program needs to have a draft PR. Since this is a UI and UX task (at least the part tied to the Bounty program), @Mayaleeeee, you should create a Figma file and share it here. You can create in on the AsyncAPI workspace in Figma. Let me know if you need more permissions to do it. |
Or, since it is CLI, which is text-only by default, there might be a text-only (non-graphical) description of changes utilizing GitHub's terminal font (with three backticks) on
|
If I were doing this code-related strictly textual UI/UX design task as a non-coder, I would still use VSCode to take a look at the Then, I would run different variations of the And simultaneously with all this, I would be editing a large text file, which I would post here as one big comment (and update weekly) to provide a measurable deliverable for this task, with the following information: Improving error messages./src/commands/new/file.ts
./src/errors/specification-file.ts
Improving the
|
From what I understand (correct me if I'm wrong), part of this issue requires improving the design of the CLI UI/UX. This means whatever Maya is currently designing, a developer needs to implement the designs to the CLI. This issue is a sub-task of #551, and only the design part is of the Bounty? Question? Will the implementation have a follow-up issue? cc @fmvilas |
This issue is both design and code. The bounty is just about design. |
Copying from a private conversation with @aeworxet 👇 @Mayaleeeee —like the majority of the designers— doesn't feel comfortable with Markdown. The beginning of the process is a set of wireframes and at the end she'll have high-fidelity prototypes which may or may not be done with Markdown (most probably not). We should respect every profession dynamics instead of trying to impose dev stuff on them. If what we're looking for is metrics to show to potential sponsors, cool, but I honestly believe that the only metric potential sponsors will care about is finished vs unfinished issues. They'll want to know that their money is actually serving a purpose. Whether someone pushes every week or rather waits a month and then pushes all at once in one week will be irrelevant for them IMHO. It will be relevant for us though, so that we understand how people are approaching these issues but for that you don't need to enforce a draft PR but just recommend it. Or just enforce it for code issues and maybe technical writing issues but not all kinds of them. |
Thanks for the clarity. What I can suggest is that Maya shares her weekly progress reports here on the issue like how we did in the Bouny trial (for progress tracking). As she progresses, she can later share the Figma board or file that she's working on. |
Yeah, that should work 👌 |
Project Progress Overview: Weeks 1-3 UpdateHello, everyone. I apologise for the delay in providing an update on this issue. Here are the lists of materials I have been exploring.
For this week Thank you, and have a great day! |
Project Progress Overview: Weeks 3&4 UpdateHello everyone, Over the past two weeks, I have been refining the asyncapi --validate states and enhancing the clarity of error messages. I crafted six distinct states, covering valid and invalid scenarios, each with and without recommendations. You can explore these states in the attached visuals or the linked Figma file. This week, I look forward to delving deeper into this material and exploring another command for the CLI. Have a wonderful week ahead!
cc @fmvilas |
@asyncapi/bounty_team |
Hello Everyone. I want to request an extension for this bounty issue. For the past two weeks, I have been busy with exams and I could not work on it. I just resumed to working on it this week, and I would really appreciate if the deadline could be extended to 2 weeks. Thank you. |
It's totally fine from my side. I also underestimated the length of the issue. There are lots of commands and potential errors to cover. @Mayaleeeee you're doing great progress so far (even with the exams) so I think it's fair to extend the period. PS: But that's not for free. As a payback, you need to return the swag you won during the AsyncAPI v3 celebration 😄 😜 (I'm kidding, just in case 😄) |
Bounty Issue's Timeline Extended
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better. |
The swag that's on it's way to Nigeria already 🤣🤣😂 |
Project Progress Overview: Week 5 UpdateHello everyone, You can check out these states in the visuals attached or by accessing the Figma file. |
Week 7 Progress Update: I took a break during week 6 for Christmas and New Year.Hi there, For the 1. Creation 2. Validation 3. Interaction For the
2a. Error state You can also check out the states by accessing this Figma file. cc cc @fmvilas @thulieblack @aeworxet |
AsyncAPI Maintainer (@fmvilas) was absent online in Slack for two periods of three working days in a row, so all remaining target dates of the Bounty Issue's Timeline are extended by three calendar weeks. Bounty Issue's Timeline Extended
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better. |
@Mayaleeeee, please provide an update on the Bounty Issue. |
Hello @aeworxet, I apologize for not providing an update on the project. Let me explain what happened. Last week, I worked on a Thank you for your patience and understanding. |
Hello, everyone. I am pleased to announce that I have completed this issue. Below you will find the proposal for the CLI command. Proposal for the CLI CommandSTRUCTUREEvery CLI command should follow a consistent structure for successful and errored results. 1. Successful Result:
2. Errored Result
3. Missing Information
Consistent Message Formats for CLI ResponsesThese formats are proposed to provide users with informative and easy-to-understand feedback, whether the operation is successful, encounters an error, or requires additional information. 1. Success Messages 2. Error Messages 3. Prompt 4. Highlighted Words CLI Command RecommendationsHere are recommendations for improving the CLI commands: validate, generate models (--raw), generate models & fromTemplate to enhance the user experience.
Figma FileTo view the designs, please refer to this Figma File |
Just a suggestion @Mayaleeeee. Do you think these can be aligned? Also are emojis really needed, as it can become a pain if the output is piped into some other command. Any thoughts @fmvilas? |
Yeah, agree that there are too many emojis 😅 Making it hard to read the messages themselves. I think @Mayaleeeee should come up with a different design but using the same structure IMHO. In any case, this is not part of the issue itself. I think Maya did a great job analyzing the UX and came up with some design guidelines. Colors, emojis yes or no, and things like that can be worked later on too, most probably as part of a CLI design system. I won't worry about piping to other commands as these are the kind of messages that are meant for the user to see in the screen. There are ways to detect if a command is being piped or if there isn't any use behind (like in a CI/CD). We can simplify this output for this cases. |
@aeworxet bounty completed 💪 you can go ahead and instruct @Mayaleeeee how to get the payment. |
Design part of the Bounty Issue Completed 🎉Please go to the AsyncAPI's OpenCollective page and submit an invoice for |
I love this initiative, thanks @Mayaleeeee for this amazing work, I suggest taking the next iteration under the umbrella of the new DX working group |
Thank you, @Amzani. I owe it all to @fmvilas for his guidance and support. 🙌🙌🙌 |
Implementation part is completed in #1214 |
Reason/Context
The current CLI is great but lacks some consistency and quality in how we handle user errors and mistakes. On top of that, we could be doing a better job in making it look nicer, although that's secondary IMHO.
A CLI with a great user experience should help the users navigate it easily, recover from bad states (errors/mistakes), and move forward after a command has been executed. Especifically, when it comes to error messages, it always comes to my mind this image:
We have a bunch of this ☝️ We should instead aim for something like this:
This article is really good in case you're interested: https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f
Description
So, what are the tasks to do here? I just came up with a few ones but feel free to suggest adding others:
--help
command listingThe text was updated successfully, but these errors were encountered: