Page MenuHomePhabricator

MPIC: Improve application copy
Open, MediumPublic5 Estimated Story Points

Description

Problem

There are inaccuracies and inconsistencies related to copy syntax and style across the MPIC application. For example, titles and labels use different capitalization (title case v. start case); field descriptions mix declarative, interrogative or imperative voices.

Writing could also be improved in order to hopefully ensure more clarity. For example, some labels and descriptions can be perceived as redundant (e.g. Schema type: Which schema are you using?) or unclear (e.g. By proceeding, I acknowledge that running an instrument has risks. ).

Suggested solution

Adjust the copy of titles, labels and descriptions across MPIC's interfaces in order to use consistent syntax and voice, clarify meanings and optimize the amount of text used in the UI (all following Codex Style guide’s Copy guidelines).

Technical writing and UX specialists are joining forces to create a copy inventory and suggest content alternatives in this Google sheet.

User feedback gathered during the MPIC usability exploration (see T376120) will also be factored in when defining new copy.

Acceptance criteria
  • MPIC interfaces display consistent, clearer UI copy that support user comprehension

Event Timeline

Update: @apaskulin and I will be reviewing and recommending new versions of MPIC's contents (labels, descriptions, helper texts) in a separate document. We'll ask for review once the alternative copy proposals are ready.

Milimetric set the point value for this task to 5.Oct 3 2024, 11:18 AM
Sarai-WMF renamed this task from MPIC: Improve form copy to MPIC: Improve application copy.Oct 4 2024, 5:26 PM
VirginiaPoundstone raised the priority of this task from Low to Medium.Oct 15 2024, 8:50 PM

@Sarai-WMF are you done with this? Is it ready for implementation?

Hi @VirginiaPoundstone! There are some suggestions that need your review. I just pinged you in comments directly on the file. Once we have final versions of those, we'll be done. Thanks for your help!

@VirginiaPoundstone As mentioned, after the team checked the suggestions, there's help needed from product to define/improve a couple of copy bits. I'll expose them here because the copy spreadsheet we've been working on can be hard to navigate. I don't believe any of this is blocking, and that the implementation of the copy changes could start while we figure out these last details:

  • [Instrument and A/B test forms] Description field: Users missed some guidance here. How might we use to field's description to clarify to them what kind of information they should provide in this field? Should we recommend reusing any of the contents of the measurement plan (e.g., their hypothesis)? // Current suggestion: "Provide a brief summary of this instrument’s purpose and key details for future reference"
  • [Instrument and A/B test forms] Compliance requirements: The meaning of this field wasn't clear to users. How might we let them know what exactly they need to indicate here and where to find that information? // Current suggestion: "Select the data compliance requirements that apply to this instrument"
  • [A/B test forms] Concurrent A/B test warning message: We should provide more guidance to help users avoid any issues, instead of just warning: What can users do to avoid concurrency issues? Should we say "Avoid running A/B tests..." instead?, should we encourage them to take specific measures? Which? // Current suggestion: ""Running A/B tests during the same period of time can risk contaminating the results. Overlapping tests may make it harder to accurately measure the impact of each change."
  • [Instrument and A/B test forms] Risks acknowledgement checkbox: Being discussed in T377315. Latest proposal: "I confirm that I've followed the data collection guidelines and determined that this instrument is low risk, or that I have completed the necessary mitigations in case a Security and Legal review was required."
  • [Instrument and A/B test forms] Description field: ✅
  • [Instrument and A/B test forms] Compliance requirements: ✅
  • [Instrument and A/B test forms] Compliance requirements: ✅

This needs to first ask: "what is the data collection risk level of this instrument [or A/B test] according to the legal guidelines: https://foundation.wikimedia.org/wiki/Legal:Data_Collection_Guidelines":

  1. select risk level from a drop down ("Tier 1: High risk, Tier 2: Medium Risk, Tier 3: Low risk")
  2. a. if risk level selected in medium or high, they are asked: "please add a link to the L3SC process approval" (this may need to be a PDF upload? need to check with Mikhail about what format these approvals come through as)

2.b. If the risk level is selected to be low, then the URL/upload field is inactive with a message that states: "Tier 3: Low risk does not require an L3SC review."

Summarizing status here. All copy suggestions are ready, with a couple of exceptions:

  1. [A/B test forms] Concurrent A/B test warning message: This is still work in progress, with an exchange ongoing in the Alpha copy sheet. I wouldn't say the task should be blocked by this. Changes could start being applied while we finalize a decision.
  1. [Instrument and A/B test forms] Compliance requirements: @VirginiaPoundstone is suggesting a very appropriate update of the Regulation section, which I believe should be addressed in a separate task. I'd suggest skipping this section and not applying any copy changes to the fields included in it as part of this ticket. I tried the behavior described in T380592: MPIC: Improve Regulation section: the task is now ready for your review 🙏🏻