search

department-of-veterans-affairs / va.gov-team

Public resources for building on and in support of VA.gov. Visit complete Knowledge Hub:
https://depo-platform-documentation.scrollhelp.site/index.html
282 stars 202 forks source link

Provide design system team with error message examples from different categories #48825

Open RLHecht opened 1 year ago

RLHecht commented 1 year ago

Issue Description

The design system team is working on a pattern for helping users recover from error messages. Danielle separated out the error messages into 5 categories:

  1. System: Alerts the user of important system-related issues or status. It’s initiated by the system and it’s not a result of the user’s actions.
  2. Engagement: Nudges the user to enter or update data in the system. It can be initiated by either the system or another user.
  3. Access: Appears when the user tries to access an item that’s not available to them. It may be because the record has been deleted, the user doesn't have access, etc.
  4. Feedback: The application’s response when the user is interacting with it. The majority of create, read, update, delete (CRUD) actions will result in feedback messaging.
  5. Sign in and identity verification

We need to look for 1 or 2 error message examples in each of these categories and give the list to the design system team.

Tasks

Recover from errors pattern

Error messages section of style guide

Acceptance Criteria

aliyahblackmore commented 1 year ago

11/2 update: I will come back to this work on Monday and continue to compile different examples. Also noting that in our call with Danielle, Laura flagged the related error messages content ticket that may loop in to this work.

aliyahblackmore commented 1 year ago

Hi @laurwill! These error message examples are ready for you to review!

As discussed with Danielle, we confirmed that for the time being I'd look at/reference the error message dictionary and matrix and make language changes/suggestions as needed so that messages are more aligned with current style standards. The goal in compiling this is to give a general idea of our style - we don't have to worry about whether matrix or dictionary content was most up to date.

I included 1 to 2 examples for each category and included a few changes (i.e. using "We're sorry..." were it seemed appropriate, etc.). I found that the error message dictionary was most helpful and referenced it while I compiled these.

Thank you! Error message examples _11.16_AB.docx

megzehn commented 1 month ago

Pulling this ticket out from the grave for an update.

We changed direction and focused on some more general updates on the DST pattern for Recover from errors. Here are notes from Laura:

Recover from errors pattern:

We want to suggest moving much of the content guidance out of this pattern page. Much of it is about other types of alerts (not about error messages) and we want to centralize content guidance for errors in the style guide. We’re suggesting that we narrow this pattern page down to 2 streamlined sections:

  • How to structure an error message (1. Explain problem 2. Explain how to fix it)
  • Common contact options for error message recovery steps (standardized text for VA hotline numbers and guidance for when to use each o
  • Here's a rough in-process draft of the suggested updates: Recover from errors.docx

Error messages section of style guide:

We want to restructure this section to acknowledge that much of the guidance and dictionary content is actually for info, success, and warning alerts, and not only for error messages. We also want to consider changing the 4 categories of error messages to better align with how designers and product teams think about different types of alerts and errors.

  • Rename the page to "Alert and error messages"
  • Move all general language and style guidance for alerts and errors to this page (from "recover from errors" pattern and elsewhere)
  • Build out updated examples of the most basic and common error messages (and then work with customer support team to add the more complicated ones)
  • Replace the existing 4 categories of error messages (System, Access, Engagement, Feedback) with new categories for types of alerts. Error messages will be one type of alert, with its own examples. Here's a rough in-process draft: Alerts and error messages.docx

For the first step of this work, @laurwill overhauled this DST pattern and got this initial version approved by Danielle, Mikki, and Chante.

Matt just reviewed and merged it, so it's live in the DST.

Our next step will be to keep working on the next iteration of the Error messages part of the style guide. And then to share these updates with the larger CAIA and design teams.