Identify possible overlay error message categories and apply error message template
- Dominant language
- Go
- Stars
- 1.9k
- Forks
- 167
- PR merge metrics
- No merged PRs in 30d
Description
@cari-lynn commented on [Thu Jan 28 2021](https://github.com/vmware-tanzu/carvel-imgpkg/issues/69)
#### What are "helpful error messages"? Ask yourself these five questions to start:
Does the error...
1. focus my attention on the source of the problem?
2. give all of the relevant facts (and none of the irrelevant ones)?
3. consistently use a set of accessible terms?
4. make clear what's wrong?
5. help me figure out how to fix it?
#### What were the results from the initial round of user testing?
[During the first rounds of user testing](https://hackmd.io/qOdnXOdHQbmP6i7wTOgKMg?view#Results), we found that our proposed error messages had addressed questions 1-4, but lacked any guidance on how to fix the problem. Since we know that our proposed changes to the error messages are improvements (based on user tests), we think it would be smartest to implement these improvements iteratively, rather than waiting until we have the "perfect" error message.
#### How
During the user testing stage, we worked out a general template on how we want the new error messages to look, however we only drafted complete errors in three different scenarios.
**Template Error Message**:
```
ytt: Error: Overlaying (in order: ):
Expected:
: (, '') to match item in
: ( in '') but matched .
:
:
```
Since an overlay can match via an expression, the domain of overlay error messages is vast, making it difficult to implement changes. In order to address this, a [HackMD Doc](https://hackmd.io/mVrrCDjJQJapmUVUUBeDlw?view) was created with a subset of scenarios and proposed errors. This document will also act as the acceptance criteria for the following implementation story.
#### Acceptance Criteria
Update this [doc](https://hackmd.io/mVrrCDjJQJapmUVUUBeDlw?view) with the new error message improvements. The implementation will be done in a separate issue.
#### Notes
- At this time, [this document](https://hackmd.io/mVrrCDjJQJapmUVUUBeDlw?view) is not the source of truth, and we are looking identify more error scenarios. Once an example error message is fleshed out for each major category that is identified, there should be enough information for implementation to begin.
- First round user interview doc: https://hackmd.io/qOdnXOdHQbmP6i7wTOgKMg?view
- Proposed error message doc: https://hackmd.io/mVrrCDjJQJapmUVUUBeDlw?view
- If you would like to provide feed back on the proposed error message, please capture that in a HackMD document so that we can include your thoughts during the next round of user testing.
Contributor guide
Research direction
Start with the proposed error message HackMD document and compare it with the linked user-testing results. Identify major overlay error categories and add a fleshed-out example message for each category to the proposed document. Done means the document contains enough scenarios and acceptance guidance for a separate implementation issue to begin.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100