Design for links that have google docs version

[jstrothman]

Point of contact on this issue

@bpdesigns or @MelissaBraxton

---

Timeline
Does this need to happen in the next two weeks?

• Yes
• No

How much time do you anticipate this work taking?
1-2 weeks

Background
The UX Guide has many links that are available as a web page as well as a Goog Doc version for internal reuse purposes.

We use the following to distinguish these links:
[link text for web-based link]. (18F/GSA access only 🔒 )

There are a few problems with this:

1. It doesn't pass WCAG Success Criterion 2.4.4 Link Purpose (In Context): The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general. Example problems this causes:
   • For screen reader users who pull up a list of links and listen to the links, they don't know what each 18F/GSA access only lock goes to. This is a common screen reader user action.
   • It requires unnecessary effort for speech-to-text users who are trying to target the intended 'Read more' link
2. It's difficult to distinguish from links where we only offer the GSA-only link. The only difference is the period and space at the end of the web-based link. I get daily emails with Drive requests for access to these docs.

Screenshot of similarity between 1 link and 2 links

Screenshot of screenreader links list with repeated ambiguous 18F/GSA access only links

Acceptance criteria (we'll know we're done when…)

• The purpose of each link in the ux guide can be determined from the link text alone or from the link text together with its programmatically determined link context
• People easily know if they click on a link whether it is an internal and external links
• Considerations for applying the approach we take are documented in a place other guides/sites will find it

Tasks

• Design alternative for displaying links to alternate versions of the same content
• Design peer review
• Update all such links in the 18F Methods
• Update all such links in the UX Guide
• Tag UX Guide and Method product owners to review
• Document approach in a centralized place where other 18F products can find it

[katefisher808]

Would we want this work to be translated to both the 18F Handbook pages as well as the Guide pages?

[bpdesigns]

@katefisher808 yes. The last item in the task list is documenting how this was done. One of the ways it could be documented is in another DA Team issue to review the handbook and other guides for similar situations.

[bpdesigns]

It makes me wonder if another outcome of "Document approach in a centralized place where other 18F products can find it" might be to create a wiki in the DA Team repo that shows all the work that relates to improving multiple repos. For example the 18F UX Guide documents automations like syncing across repos that might be worth greater visibility in a DA Team repo

[katefisher808]

Thanks Ben! That makes sense. I'll follow-up on how to translate direction to other places once we narrow down to a direction.

I started a doc with initial exploration for the ux-guide as a starting point. I'm going to meet with a few 18F staff to get initial feedback on the suggestions to try to narrow down directions.
https://docs.google.com/document/d/18a2YMYhthITego22yNfEhK9FpY9A4kmys1BbiuLfXk8/edit#

[katefisher808]

A heads up to watchers on this ticket. It is on hold until an engineer comes onto DA to support, which should be this week.

[katefisher808]

I'll also send this note on slack for visibility. @bpdesigns

@geekygirlsarah is on board to support from engineering team!

Update:

• From the design standpoint, We have narrowed to three possible treatments for review.
• From the engineering standpoint, we are exploring how best to implement the future changes on github across the ux-guide.
• From a cross-product standpoint, we want to open new tickets for making changes to the handbook, other guides, and for documenting the change, so we can keep this ticket moving along

[bpdesigns]

Looks great! Treatment 3 stands out to me.

[katefisher808]

@bpdesigns phew! updates have been made to the ux-guide based on the recommendations and quick discovery process.
https://ux-guide.18f.gov/

Hats off to @geekygirlsarah on untangling a lot of the rules around the links.

Next steps: we are going to open new tickets for adjusting other guides, handbook and flag it for the respective product owners.