Review position of help text on data entry screens

[emmajclegg]

User story:

"As a user, I expect help text to be accessible in the interface and written clearly so that I am supported to complete each data entry field"

Context

IATI Publisher has two sources of help text in data entry forms:

1. Hover over ? icons which present information from the IATI Standard and a link to online IATI guidance
2. "Help" labels that the user can click on, which show a yellow text box on the right hand side of the form

User issues

• Position and control of both sets of help text could be improved for user accessibility - it is very easy to miss yellow text boxes on the right-hand side of the screen, and hover over icons can be hard to use for certain users.
• Multiple sources of (often similar) help text can overwhelm the user, particularly for simpler elements with a single data entry field - e.g. activity-status:
  
• The hover ? icon guidance is more likely to be seen by the user, but contains the more technical, and perhaps less useful, IATI Standard reference guidance

Requirements

Can we ensure that:

• yellow box "help" text appears in an intuitive place on the data entry form (e.g. where the user clicks) so that it is easy for the user to see
• all help text boxes are accessible - e.g. being able to click to dismiss them
• sub-text that is not clickable should not appear to the user as if it is - e.g:
  

Implementation idea

This would remove the need for two sets of yellow box text (but let's discuss):

1. change the ? hover over icons to display the plain English help text instead (i.e. what currently appears on the right hand side of data entry forms)
2. link to the IATI Standard reference webpage from the element name itself
   

Considerations:

• ODS will be reviewing English interface text as part of Task for ODS - Review extracted English text and send for translation (French/Spanish) #1483

[shreyaydi]

The placement of help texts was a significant discussion in the project's initial phase, influenced by the content of the help text. The "?" icon was intended for immediate help texts with a link to the respective IATI Standard, while the "Help" button would provide more detailed information, if available for that particular element. However, we could de-clutter by combining both help texts under a single "Help ?" icon with an "Expand" or "Show more" link. Clicking this link would display additional information in the same popup, allowing users to scroll through the extended text.

Regarding the help text being triggered on hover, we would like to understand the concern further. What issues did users encounter when they hovered over the icon? We initially chose hover-triggered help text to reduce the number of clicks for users and to enhance accessibility. However, if there is a case where help text closes when users slightly move out of the hover area, using a click to trigger the help text might be more practical, especially for longer texts.

For the issue of "Multiple sources of (often similar) help text can overwhelm the user, particularly for simpler elements with a single data entry field - e.g. activity-status:" we believe that both the element (activity status) and the input field have their own help texts. The element's help text explains what the element is, while the form element's help text pertains only to the form.

[emmajclegg]

However, we could de-clutter by combining both help texts under a single "Help ?" icon with an "Expand" or "Show more" link. Clicking this link would display additional information in the same popup, allowing users to scroll through the extended text.

@shreyaydi - I think this would be the ideal solution for simplifying the interface. I suspect IATI Publisher's plain English help text is more useful to the user than the IATI standard reference text in most cases, though I'll get a second opinion from my team tomorrow. And a "Show more" option to expand the message makes sense.

Regarding the help text being triggered on hover, we would like to understand the concern further. What issues did users encounter when they hovered over the icon? We initially chose hover-triggered help text to reduce the number of clicks for users and to enhance accessibility. However, if there is a case where help text closes when users slightly move out of the hover area, using a click to trigger the help text might be more practical, especially for longer texts.

I noticed that the two sets of help text are currently triggered and dismissed in different ways in IATI Publisher and I was trying to establish what best practice is. Again, I'll try to get a second opinion, so leave the hover over icon working as is for now.

For the issue of "Multiple sources of (often similar) help text can overwhelm the user, particularly for simpler elements with a single data entry field - e.g. activity-status:" we believe that both the element (activity status) and the input field have their own help texts.

This would not be an issue if we found a way to combine the two sources of help text into one, as discussed in the first point above.

---

One question - is all of the help text currently hard coded in IATI Publisher, or is the IATI standard reference text displayed in an automated way from the IATI schema code?

[emmajclegg]

To add a few points after discussing this with my team today:

• we all think that the plain English guidance (i.e. what currently appears on the right hand side of the screen) is more helpful to users than the IATI Standard reference, so ideally it should be the first thing users find.
• a link to the relevant IATI webpage for each data element is useful, but the IATI Standard reference text itself doesn't necessarily need to be displayed in IATI Publisher.

Once I have a clearer sense of how much of this guidance is hard-coded vs. easy to move around, I'm happy to discuss options.

[Yash-ftW]

Hi @emmajclegg,

One question - is all of the help text currently hard coded in IATI Publisher, or is the IATI standard reference text displayed in an automated way from the IATI schema code?

Currently, In IATI Publisher all of the help text are not hard coded but retrieved from a JSON File elementJsonSchema

[emmajclegg]

Hi @Yash-ftW -

IATI Publisher's hover text looks like it uses the element-level "documentation" from the IATI activity schema code:

My question was when that documentation changes in the IATI activity schema, does IATI Publisher's hover text automatically update? The hover_text in elementJsonSchema looks hardcoded so I'm assuming the answer is no.

It's worth us discussing this in the context of #1477 - as this text will need marking for automated extraction anyway, it might be a good opportunity at the same time to review what displays where in the interface.

[PG-Momik]

@emmajclegg

My question was when that documentation changes in the IATI activity schema, ...

No. As you've guessed, the json file doesn't change even if the activity schema changes.

Currently:

• Some help texts are derived from the Guidance page and others from the IATI Standard page.
• Most hover texts are taken from the IATI Standard and then reviewed and shortened in the initial discussion. (I've shared a file that i think is relevant to this discussion, it contains the initial hover texts)

we all agree that the plain English guidance (currently displayed on the right-hand side of the screen) ...

Some other possible solutions:

1. Swap help text and hover text content.
2. Increase help text box size and move it to the center of the screen
3. Merge both help text and hover text content and display them in hover text.

We can have a discussion on how to move forward in our next call.

---

cc: @BibhaT

[emmajclegg]

3. Merge both help text and hover text content and display them in hover text.

^^ This is the solution I suggested on today's call - it sounded like you were in agreement (@BibhaT @PG-Momik )

Having one rather than two sources of help text for each data entry field should be easier to maintain in future. My plan would be to keep the plain English help text in most cases and remove the IATI Standard reference text, unless it adds useful information. The "for more information" link can be kept as a way for users to view the technical Standard guidance online if they want.

You suggested writing a script to extract the plain English help text as a next step. If it makes sense to wait for work on #1477 to progress to make this easier, let me know.

[PG-Momik]

@emmajclegg The help and hover texts have been extracted and shared. Ideally it would be better if the texts were reviewed and this issue to come into a decision on the requirements.

Given that the texts are reviewed, corrected or even discarded based on relevancy and usefulness, we would implement those texts into the system. Once implemented, the scripts used by @Sanilblank would handle them for the translation modules.

cc: @BibhaT

[emmajclegg]

Ok thanks for sharing the text @PG-Momik. It'll take me a bit of time as there's a lot to review - I'll post an update how far I've got next week.

[emmajclegg]

Hi @PG-Momik - to update on this, I'm editing the help text in a copy of the file you shared with me: Help and Hover texts (ODS reviewed).

I have finished reviewing the sheet "Organisation Help and Hover Text", and am half-way through the "Activity Help and Hover Text" sheet.

To summarise, I've tried to:

• reduce the amount of text by combining help_text and hover_text into one
• populate the hover_text field, leaving help_text blank for all fields except language and currency
• reduce the number of hyperlinks by keeping one link per element, and some others that look particularly useful
• make help text consistent across similar data entry fields (e.g. for 'period start date'). This should make translation easier.

I have asked a colleague in ODS for advice on how to make sure the help text pop-ups are accessible in the interface, and will report back any tips here.

Any questions so far, let me know. Otherwise, I'll continue the activity text review and aim to finish by the end of this week.

[emmajclegg]

@PG-Momik @bibha - to confirm, I've finished review of this helptext in the file Help and Hover texts (ODS reviewed).

The same summary points as above apply. I have done my best with the HTML text, but obviously check links are rendering ok and let me know any problems.

Some helptext appears in multiple places (e.g. document-link sub-element descriptions), so it would be good to ensure that we're extracting, translating and reintegrating those helptext strings once rather than multiple times.

In terms of format of the helptext boxes in future, this is the advice I received about accessibility:

I think either of these dialogs' positioning is fine, although I would opt for the position of the current hover text if you want to consolidate them. However, in general, things that only appear on hover (i.e. appear on mousein then disappear on mouseout) are discouraged; making the dialogs persistent is better. Also I wouldn't worry about limiting user clicks as it's better to have something that's keyboard-accessible that requires an extra click. See here. A good practice is to add an event listener to listen for the Esc key and close when it's pressed, even if the focus is elsewhere. Speaking of focus, I think making the dialogs non-modal (i.e. allowing the page to continue to be interacted with beneath the dialog) is best, but allow the user to tab to the interactive elements within the dialog.

So, the position of the current hover text is fine, but it would be better to click to open and click to dismiss is my interpretation!

[emmajclegg]

@PG-Momik - to clarify after your question this morning, I think it's fine to not have hover text for the language and currency data entry fields. The help text underneath (which I haven't changed) seems sufficient for now.

Any problems or other questions, let me know.

[BibhaT]

Hi @emmajclegg,

We have iterated the help text box and have come up with two options as follows:

Option 1-

• Use of (?) Icon: We have retained the (?) icon because it is a universally recognised symbol for help (we can change it to "Help" if this does not make sense to you)
• "Help" text when hovered on (?): Provides clarity by labelling the icon as "Help" and addressing potential user confusion without requiring clicks
• Highlighting the Yellow Box: The overlay momentarily emphasises the help content, ensuring visibility without disrupting workflow
• Side Placement of Information Box: Keeps the content accessible while allowing users to reference it without obstructing the main interface and does not disrupt the workflow
• Have a look here: https://www.figma.com/proto/upgUy5i65LYC3iiqYVnACW/IATI-Publisher-Platform?page-id=[…]dth&content-scaling=fixed&starting-point-node-id=17350%3A21813

Option 2-

• Here, the help box will appear at the centre of the page and will slide off to the right hand side within seconds. This brings the users' attention to the box and since it will stay put at the right side of the page, they will be able to refer to it when filling up the forms.
• Have a look here: https://www.figma.com/proto/upgUy5i65LYC3iiqYVnACW/IATI-Publisher-Platform?page-id=[…]dth&content-scaling=fixed&starting-point-node-id=17350%3A22929

Have a look and let us know!

@Yash-ftW @PG-Momik

[emmajclegg]

Hi @BibhaT - thanks for the options. I think the current "?" icon is fine to use in the interface for this help text.

I was envisaging that we keep the hover text placement where it currently is in the data entry forms (i.e. appearing at the location of the "?" icon) - is there a reason for not wanting that?

Note that I've shortened most of the help text to a few sentences, so there won't be any text as long as in the Figma examples you've shared. For that reason, I don't expect users to be keeping it on screen while they complete the form - instead, they can hover or click to open it, read it, click to dismiss, then complete the data field. Or they might click through to the website for more detailed information.

I'd avoid any movement of the help text box (i.e. option 2).

However, in general, things that only appear on hover (i.e. appear on mousein then disappear on mouseout) are discouraged; making the dialogs persistent is better.

This was the main feedback ^^ I took from my colleague. The help text appearing on hover is great for sighted users, but not detectable to screen readers is my understanding. Clicking to dismiss the help text seems fine for all users.

[Sanam-07]

@Yash-ftW
I’ve reported some bugs in #1655. Could you please review them when you get a chance?

[Yash-ftW]

@emmajclegg, This has been deployed to staging.

The changes done are:

1. Added the on click effect instead of hover.
2. When clicking outside the box or pressing ESC the box closes.

[emmajclegg]

Hi @Yash-ftW - this is looking great, really good to see!

The new open/close functionality and text looks good. A few, hopefully minor, design points to improve clarity:

• Can we remove "IATI standard reference" from the top of each help text box? It no longer applies in most cases as we've kept the former "plain English" help text.
• Is it possible to a) make the "x" symbol to close the box slightly bigger and b) the help text black instead of grey, so that both are as easy as possible for users to see?

If either of these are not simple changes let me know, and we can decide what's worth doing.

[Yash-ftW]

Hi @emmajclegg, Changes have been deployed to staging. Please let me know if there are any more changes to be done.

[emmajclegg]

That looks great - thanks @Yash-ftW . Go ahead and deploy!