carvel-dev / carvel-dev/ytt

Improve overlay error messages

Open
#289 1 comment 1 reaction 0 assignees View on GitHub
Epic
Dominant language
Go
Stars
1.9k
Forks
167
PR merge metrics
No merged PRs in 30d

Description

# Why?

When an overlay matcher’s expectation fails, the error message `ytt` gives falls short of helping most users determine what to do next.

_For more details see the "Problem" and "Analysis" sections in_ [Overlay message errors](https://hackmd.io/_ttxzbpASVCtKUhWSzOMfg?view)

---

# What?

Do this loop until we find a good error message:
1. design a _**little**_ user research to test an idea of a better message format
2. conduct that research
3. synthesize into one or more user stories (attach to this epic)
4. make those improvements (play the storie(s))
5. design a little more user research to validate the improvement
6. conduct that research
7. if not "good enough", goto 1

**Note:** By "little" we intend to put in the smallest possible effort that could still yield enough signal that we'll mitigate the risk we build the wrong thing. In other words, it's better to do this loop more times than it would to invest a lot in a single loop.

---

# Resources
- originating issue: https://github.com/k14s/ytt/issues/94
- public issue: https://github.com/k14s/ytt/issues/95
- [Overlay message errors](https://hackmd.io/_ttxzbpASVCtKUhWSzOMfg) _proposals for actual improvements_
- [Overlay Error Message User Research](https://hackmd.io/qOdnXOdHQbmP6i7wTOgKMg) _details of how we're conducting user research_
- Thoughts on error message UX:
- https://uxdworld.com/2018/05/30/how-to-write-good-error-messages
- The Mom Test by Rob Fitzpatrick (See team drive for this book)

Contributor guide

Open the contributing guide

Research direction

Start with the linked “Overlay message errors” proposals and “Overlay Error Message User Research” plan, then review originating issue 94 and public issue 95 for context. Follow the stated research loop: test message ideas, synthesize user stories, implement the accepted improvements, and validate them again until the messages are good enough.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.