TW audit of existing MR widgets, propose plan
As part of &5710 (closed), I need to review this Figma file:
I've kicked off the work by creating a Figma File that currently has the collection of screenshots for each widget with the addition of the Accessibility widget.
The scope of this issue is to identify a potential pattern for phrasing in these messages, and report my findings back to @icamacho, @pedroms, and @jeldergl. I'm pretty sure I'll be leaning on some of the work Pedro and I have already done, but I should examine the existing messages to be sure.
Overview, step 1
Define the language structure of widgets that are small enough to not need collapsing.
- Four types of widget: error, warning, success, info
- Emoji cannot be in the middle of a message as it's problematic for translation
- Currently open question: can a tooltip be added to a word or phrase in a message? Or will this break translation?
Error
[status]: [Next step, with <tooltip> for complex words]. «Link» {Upgrade}
Warning
[status]: [Next step, with <tooltip> for complex words]. «Link» {Upgrade}
Success
[Optional status:] [Success message] [emoji] «Link»
Info
[Optional status:] [Statement]. «Link» {Upgrade}
Definitions
- Status - Short phrase for current condition (like "Merge blocked"), followed by a colon
- Next step - Complete sentence, starting with a verb, to tell the user how to fix the problem. Use ending punctuation.
-
Tooltip - Complex or technical word(s) we want to define in more detail without expanding the entire message.
- (We'd also need to define the language shown in the tooltip)
- Link - A link to docs (for instructions) or the UI (for a config change) that can help the user fix the problem or learn more. Short phrase.
- Upgrade - If a higher version of GitLab provides a better experience, explain and link.
- Emoji - Use sparingly, but can help with friendly tone. Must be separate from text, because it causes problems with translations.
Overview, step 2
After we define the pattern for non-collapsible widgets, let's look at widgets that ARE collapsible to see what their needs are.