[Pattern] - Help users to...Resolve an error

[GnatalieH]

Description

When a user encounters an issue (such as a login error), we often present a bulleted list of next steps below the alert component that communicates the issue occurred. This is context-sensitive, just-in-time info that can potentially help users self-solve their issue. We should standardize the use of well-formatted text (in plain language) along with headings to clearly communicate next steps.

Details

This pattern request came from the VA Content team and was supported by @allison0034 and @seanasewell from the Collab. Cycle.

Here is an example:

Tasks

• [ ] Write or update component documentation for design.va.gov using the appropriate maturity scale tag
• [ ] Coordinate with accessibility specialist to create or update accessibility guidance
• [ ] Request documentation draft review
• [ ] Once documentation is approved, publish to design.va.gov

Acceptance Criteria

• [ ] Pattern documentation is published on design.va.gov

[GnatalieH]

This ticket should also address updating the incorrect error alert image that lives in the existing pattern; note the typo (andy):

[GnatalieH]

Meeting between me, Matt, Danielle, Randi, and Beth on 10/4. We decided these will be our next steps:

• I will be chopping out a lot of content from the existing pattern because it is outdated and too lengthy.
• The revised pattern will include guidance on inline errors in addition to addressing when to use an alert vs. background only alert.
  • I will pull in examples of alerts from Storybook.
• We will also address how and when to use text outside of the alert itself to help users recover from errors (see image in this issue).
  • Danielle will connect me with the team who is doing content-related work on this pattern.
  • Content will be working on their guidance and will identify the issues in the screenshot, as some things like the telephone link are incorrect.
• I'll create an outline of the revised pattern to share with everyone this week as a first step. This work will need to be done in phases because it covers a lot of use cases.

[humancompanion-usds]

In the comment above it says that this pattern will address inline errors but in the pattern guidance there is a "When not to use this pattern" section that says:

This pattern does not apply to inline errors. Guidance on creating inline form field error messages will be handled in a separate pattern.

So which is it? Same issue with the "How to design and build" which has sections for Alert but not for background-only Alert. Pattern guidance shouldn't duplicate component guidance. It should direct users of the system to the appropriate components but more importantly it should answer the questions users of the system may have around helping users recover from different types of errors.

We will also address how and when to use text outside of the alert itself to help users recover from errors (see image in this issue).

Which section is this going in? I can't tell from the outline.

[GnatalieH]

@humancompanion-usds

In the comment above it says that this pattern will address inline errors but in the pattern guidance there is a "When not to use this pattern" section that says:

This pattern does not apply to inline errors. Guidance on creating inline form field error messages will be handled in a separate pattern.

So which is it?

Good point. I got confused when I first edited this pattern because it has the italicized text near the top of the page about inline errors being handled in a separate guide. I think we can include a section about inline validation errors. I'll update the guidance.

Same issue with the "How to design and build" which has sections for Alert but not for background-only Alert. Pattern guidance shouldn't duplicate component guidance. It should direct users of the system to the appropriate components but more importantly it should answer the questions users of the system may have around helping users recover from different types of errors.

Gotcha. I'll work on this. I realize the omission I made, and I want to rethink this outline so it's centered around recovery per error type, and then talk about the types of alerts that support those scenarios.

We will also address how and when to use text outside of the alert itself to help users recover from errors (see image in this issue).

Which section is this going in? I can't tell from the outline.

I was thinking Supplemental content but am curious what others think makes sense.

[GnatalieH]

I have made lots of updates to the PR since my last comment. I also created this Mural board to help visualize and think about the Content style guide Error messages section. Ready for your review @humancompanion-usds.

[humancompanion-usds]

This doesn't seem finished:

• There are no examples from Storybook, just a list of examples. The examples here are more a description of the types of error messages. That's already defined here: https://design.va.gov/content-style-guide/error-messages/#messages-dictionary Thus we should pull that content in as an include. I see now that's a separate issue so I'll leave it be but we can't really ship a pattern without examples.
• The only image that is included is broken. It should use the include from the component template.
• I can see that the image upload is the same one that Allison or Sean provided but it's blurry and not clear enough to read. Please get a better screenshot.
• The very start of this pattern is unclear: "When a user experiences a critical or recoverable error" - What is an example of a recoverable error? (I know the answer but the reader may not).
• "Background alerts are usually triggered by a user-initiated action. They appear below the H1 and contain the following elements:" - Alerts also appear below the H1. In fact, all content appears "below the H1". That's not helpful. We need to be way more specific either here on in the component docs on the placement of background alerts.

Also, the content that was on the page is still useful. It just needs to move to either the content style guide on errors or into the Alert component. But there is a lot there that we shouldn't just discard because it's long. Some of it is still relevant.

[GnatalieH]

Hi @humancompanion-usds. Correct, it's not nearly finished. Please note that this ticket was only supposed to include me creating an outline of the content. At least that is what we originally had discussed with the Content team.

• There are no examples from Storybook, just a list of examples. The examples here are more a description of the types of error messages. That's already defined here: https://design.va.gov/content-style-guide/error-messages/#messages-dictionary Thus we should pull that content in as an include. I see now that's a separate issue so I'll leave it be but we can't really ship a pattern without examples.

Yes, I created the follow up issue specifically to address the examples. The Error messages dictionary contains all kinds of messages including success and status update messages -- things that are definitely not errors. I created an entire Mural diagram to put everything in one view because the Error messages dictionary is so non-intuitive to me. Do you still want to do the includes? How do you imagine this looking -- a table below each example header?

• The only image that is included is broken. It should use the include from the component template. I can see that the image upload is the same one that Allison or Sean provided but it's blurry and not clear enough to read. Please get a better screenshot.

I'm going to post in the sitewide content-ia channel and ask Allison about this image if I can't get it myself. Someone shared this image with me originally and I don't know if I can recreate the scenario with the bulleted steps under the alert. It would take less time to recreate the image in Sketch, and then I could add a header to the Alert, too. Is that OK?

• The very start of this pattern is unclear: "When a user experiences a critical or recoverable error" - What is an example of a recoverable error? (I know the answer but the reader may not).

"Critical errors occur when a user can't complete a task, such as signing in, and may require calling Help Desk in order to resolve. Recoverable errors can be resolved by a user completing required information, correcting a validation error, etc." Something like that?

• "Background alerts are usually triggered by a user-initiated action. They appear below the H1 and contain the following elements:" - Alerts also appear below the H1. In fact, all content appears "below the H1". That's not helpful. We need to be way more specific either here on in the component docs on the placement of background alerts.

I'll have to ask Allison about this because I honestly don't know what the placement details are. I usually only see alerts in a vacuum, not on the full page. I also created another ticket to finish the How to design and build section and Accessibility and Content consideration sections.

• Also, the content that was on the page is still useful. It just needs to move to either the content style guide on errors or into the Alert component. But there is a lot there that we shouldn't just discard because it's long. Some of it is still relevant.

I agree, but we don't own the Content style guide so we'll have to bring some of this up with the Content team and coordinate. I feel like updating the Alert component should be its own ticket. I can create that if you'd like.

[humancompanion-usds]

Okay, I had thought the outline was done last sprint. If this is the outline then I'll just address the things that should be in the outline.

• RE: Critical vs. recoverable - Yes, that's exactly the level of detail we should have. I think this pattern will go on to be really focused on recoverable errors but it is worth mentioning the critical error path of having to contact support.
• RE: Background-only Alert placement - Okay, reach out to Allison. We need to document where we expect background-only alerts to go and add that to the Alert component guidance. If you add it there you likely don't need it in this pattern. You can just point the reader there with a link. Also, where the Profile team places background-only Alerts actually makes little sense to me. I'd ask Allison for other examples. We need to pick a consistent spot.
• RE: Content style guide. We co-own the Content section. Danielle and I agreed that we can contribute as long as they review it. Also, they likely wrote most of that content and all we are doing is moving it into the Content section.

[GnatalieH]

@humancompanion-usds just an update:

• I added more details to the When to use section re: critical vs. recoverable errors.
• I reached out to Allison. She suggested considering the alert placement from an a11y POV. I'm getting some input about this from DK and Adam Whitlock, an engineer. She also had some ideas around how we consider alerts in general, and thinking about things from a Veteran's standpoint. Alert fatigue is a real issue. I'll talk to you about this in our Thursday meeting.
• Haven't addressed the Content style guide, yet.

Thanks.

[humancompanion-usds]

We can keep working on the draft PR for this in the new tickets that have been created.

[humancompanion-usds]

Another item we need to cover in this pattern is whether or not to have an Alert - Error at the top of the page that summarizes the errors in the form below it. This summary would ideally contain a bulleted list of the fields in error and be links that anchor down to the fields in the form. Conferred with Danielle and she agrees. We're not sure if there are any examples of this already but we should look before writing this guidance.

[GnatalieH]

@humancompanion-usds that would be really helpful, I agree, to have that error summary example. Is this something that could appear on any page of a form (not just the Review page, for example)?

[caw310]

From a July 19 meeting it was determined that CAIA will work on this so we will leave it for now.