BitcoinDesign
Create a page for designing error states
This is based on this Tweet I posted about how to provide useful information to users when things go wrong. There was a very positive response to the post. Errors are typically not things builders enjoy detailing out, but they are hugely important to build trust and confidence in a product. It's an area where we could provide a good foundation that might save others time and effort. There's also a Slack thread about this.
Might be ideal to have one page about how to generally approach errors (maybe in Designing Bitcoin products), and individual pages and sections could address unique errors.
Some notes on potential errors page content:
- General approach
- Differentiate between user error and technical error
- Do everything you can to prevent errors in the first place by guiding users well and using under-the-hood tech approaches (X didn't work, try Y before bugging users)
- Psychology of error messages (clearly state what happened in simple language, calm user concerns, suggest solutions if possible, offer simple follow-up actions)
- Try to find error severity categories. Examples:
- Minor form validation (forgot to fill out a field, etc)
- Data validation where user might need help (BTC address invalid)
- Service problem (no route found to a node)
- Application problem that can't be avoided (app crashes)
- Try to find solution proposal categories. Examples:
- Problem is unfixable
- Not sure what happened, ask for support (share this error log in our Telegram channel for help)
- Problem can maybe be fixed if the user tries a few things (try one of these)
- Problem can be fixed by the user with a specific action (do this)
- App can probably fix the problem by doing something unusual, but needs user permission (is it OK to do this?)
- Retry later
- Design mock-ups with detailed explanations for different error scenarios
Goal with these points is to structure an approach to designing for these user experiences. I think we can end up with fairly straightforward system and guidance.
There's a number of such errors documented on the following discussion
- https://github.com/BitcoinDesign/Guide/discussions/432
Here are some Lightning error codes we should design human readable error messages for on this page: https://wiki.ion.radar.tech/tutorials/troubleshooting/error-codes
- We have errors here https://bitcoin.design/guide/daily-spending-wallet/sending/#errors
- And here https://bitcoin.design/guide/daily-spending-wallet/requesting/receiving/#failed-swaps
- And here https://www.bitcoinuikit.com/screens/flow/errors
Potentially we can add a new page in designing bitcoin products, (dealing with things when they go wrong) https://bitcoin.design/guide/designing-products/introduction/
I still think this is a good issue. Basically extract what we have in the sending page and add some more meat around it. I'd like to add this to the roadmap for Q1, for myself to work on (unless there are other takers).
Hi, so I was going through the following issue and wanted to know if it's about creating all the possible error states for just the sending page or all the possible pages of bitcoin wallet?
Hi @zealshah29, the description of the issue has a pretty good outline. The goal is not to create all possible error states, but to provide a framework for presenting errors and allowing users to deal with them, and then mock-ing up a solid set of examples. So many different things can go wrong across different application that it would be really hard to capture all possible error states.
Hi @zealshah29, the description of the issue has a pretty good outline. The goal is not to create all possible error states, but to provide a framework for presenting errors and allowing users to deal with them, and then mock-ing up a solid set of examples. So many different things can go wrong across different application that it would be really hard to capture all possible error states.
Hi @GBKS , Thank you for your feedback and clarification on the goal for the error handling framework. I would love to help out with both the content and designing UI mock-ups for the error page. Could you let me know what has been done so far?
No one is working on this at the moment. You are welcome to work on this, but just as a heads up, this is a pretty complex issue that will be quite involved.
Okay, thank you. Could you kindly provide information about the timeframe for completing this task? Knowing the deadline will assist me in determining my capacity to contribute effectively. If there's no specific timeframe, I'm prepared to engage and offer my assistance. I can establish milestones and provide regular updates as needed.
There is no timeframe for this, it is a completely open task that you are welcome to tackle as it works best for you. It is always helpful to do these things step by step and in collaboration with the others who work on the guide. We have a dedicated channel for the project in our Discord, and host calls about the project every other week, which you can find in the calendar. I'm looking forward to see what you'll come up with.