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