Extend the glossary aiming at making the UI more accessible

[gonzalo-bulnes]

Description

I am suggesting to extend of the Glossary of terms used in the user interface of SecureDrop in order to provide translators with a more precise context for effective translations.

Here are my notes, along with a few ideas about how to break this in smaller tasks.

Tagging: @rmol

User Research Evidence

When reading through the (Spanish) translations of the user interface and the comments attached to them, I observed that some terms were likely unclear to (probably) different translators. Sometimes, variations in the vocabulary used in English make unclear translations more likely.

Since clarity is important to SecureDrop users (sharing information reasonably safely is a complex task), I think it could be worth refining on the existing guidelines for user interface language.

This could be an opportunity to distill the content of the user experience design resources that are listed in the UX Wiki into a practical set of examples that are ready-to-use in SecureDrop's context.

User Stories

Goal

• As a source who isn't browsing in English, I want the explanations I read in SecureDrop to feel accurate and familiar, so that I can focus on the elements that are new to me and are less at risk of making mistakes that could compromise my safety.

• As a source, I want the vocabulary in SecureDrop to be consistent, so that I can focus on the elements that are new to me and are less at risk of making mistakes that could compromise my safety.

• As a journalist, I want the technical vocabulary to be consistent so that the authentication details don't occupy more of my attention than necessary, and I can focus on making my source's contribution worth the risks.

• As an admin, I am probably more comfortable with the inner workings of SecureDrop, but I have likely many things to think about and consistency would still reduce my cognitive load.

Means to the goal

• When I translate a piece of user interface, I can refer to a definition of the most essential terms in the context of SecureDrop to inform my translation.

• When I make decisions about UI or copy changes, I have the option to use the glossary as a support to communicate the vision behind the changes to the rest of the team, if relevant.

• When I include a user-facing string in a piece of code, I can discuss the use case with the people who wrote the string if I notice potential inconsistencies and use the glossary as a shared vocabulary to build common understanding (not all inconsistencies are bad!)

[eloquence]

Discussed in backlog review today; still a relevant issue, migrated to securedrop-docs repo where this documentation is now managed. Thanks for the detailed proposal @gonzalo-bulnes, let us know if you're interested in working on it yourself :)

[gonzalo-bulnes]

Hi @eloquence! Yes, I am interested in working on this. 🙂

What are the team's ideal timelines?

I suppose this stand up entry entry covers the stand up conversation, should I be aware of any additional context? (e.g. Is anyone else interested in this issue that I should get in touch with, or was anything specifically discussed?)

I'm happy to move the coordination questions to Gitter is that makes things easier (?)

[gonzalo-bulnes]

💡 TIL issues can be moved from one repository to another.

[gonzalo-bulnes]

Disclaimer: I can only judge confidently of the quality of translations in Spanish and French. I am familiar with the realities of translating in the context of software and can have an educated guess at what the source of some of the issues can be, but some languages differ in different ways from English than Spanish and French do, so my insights have limitations. Please bring my attention to what I'm missing!

---

The problem

Going through my notes and looking at some of the terms that seem to be difficult for the translators to place in context, I see terms that in my opinion don't really belong into the Glossary.

"Check" for example, it is used in a variety of ways with different meanings: "check again later for replies", "check your codename", "check the box". I can see that some translations in Spanish don't distinguish adequately between those meanings, resulting in confusing copy. None of those meanings are, however, specific to SecureDrop.

I believe that it could be helpful to provide additional context or guidance on how terms like "check" are used in in SecureDrop for the purpose of making the translations more accurate.
It could also be helpful to identify some of those terms and provide a developer reference for consistency (e.g. "log in" vs "sign in").

However, I also believe that their presence in the Glossary would make it less effective for an English-speaking user who is looking for information about terms that have a special meaning in SecureDrop.

[gonzalo-bulnes]

An idea (solution mode)

Create a separate copy reference.

• Goals

  • Supporting the translation teams during localization.
  • Supporting the development team during copy writing and internationalization.

• Scope: terms that describe important concepts of SecureDrop's day-to-day use that must be rendered accurately, but are not necessarily specific to SecureDrop. Someone comfortable browsing the web in English wouldn't be expected to need to look up their meaning, but consistency could decrease their cognitive load.

• Location
  The Developer Documentation seems appropriate. It already hosts the translation docs and this reference would be used by both translators and developers.
  If the translation docs were to be consolidated into their own section and re-organized, this copy reference would be a good fit for it (e.g. Developer Documentation > Translations > Reference > User Interface Copy).

I'm exploring what making space for a "Reference" sub-section could look like. Edit: here.

[gonzalo-bulnes]

Update: after a chat with @eloquence a few weeks ago, I think that making the demo instance more visible is probably a more effective, and likely a more easily maintainable way to provide context to the translators than a glossary.

One doesn't necessarily exclude the other, but I think it would be reasonable to close this issue until further notice when #167 gets addressed.