Design help text for AO filters

[noahmanger]

So that users with advanced needs understand what a filter is searching and how it works, add optional help text to AO filters that need it.

---

As we discussed in legal grooming last week, there is potentially benefit to adding some help text to certain AO filters. The point is not to provide basic instructions about how to use them, but rather for advanced researchers to be able to learn more about the details of how a particular facet works.

This is a design task to:

• [ ] Identify which filters need the text
• [ ] Write the text
• [ ] Decide the right UI

cc @nickykrause

[nickykrause]

Adding this list here for clarity

The AO search fields currently include:

• AO number
• Requestor name (AO name)
• Requestor type
• Keywords
• Document type
• Regulatory citation
• Statutory citation
• Issued date
• Request date
• Entity name

[nickykrause]

(cc @AmyKort for your reaction to my proposal below about which AO filters should have some kind of helptext and which should not, at least at first...)

My current thinking is that the filters which could use explanation include the following:

• Keywords
• Document type
• Regulatory citation
• Statutory citation
• Issued date
• Request date

I excluded Entity name from this list because the field already offers brief helptext and because, in the original user research, this field was of low importance to users.

I excluded AO number, Requestor name/AO name, and Requestor type from this list because these fields have not raised questions (yet) during usability testing, in terms of their expected behavior.

• That said, we do know that the Requestor name/AO name field seems to be searching more (at the moment) than the users think it should: https://github.com/18F/fec-testing/issues/45. However, this seems like a possible miscommunication amongst the design/dev teams for how that field should work, rather than an issue with user comprehension of the field.

Regarding the list of items that I think could use helptext, here is why:

• Keywords - The keywords are searching only within the text of the documents that have been selected in the document type field. Users may expect it to be searching more than that, so helptext could offer some clarification. Further, it may be worth noting that the keyword matching will only be as good as the digitization of the documents (the OCR process). During early research and some initial testing with folks at the FEC, users have expressed some surprise and concern about the OCR-ing. Finally, this field can accept citations, if the user wishes to search through the text of the document for citations.
• Document type - In conjunction with the helptext for the keyword field, this helptext could clarify the purpose of the document type checkboxes by acknowledging that adding or removing document types will expand or limit the keyword search results. Further, we can use the helptext to point out that final opinions are searched by default.
• Regulatory citation - During the initial research and usability testing, users have commented that they have trouble trusting citation searches when they don't know how those searches are working. This field could use some clarification to acknowledge that it does not search for citations by crawling the text of the documents, but rather by looking only at the citations that were coded against the case when it was published (i.e., the meta data). Searching for citations in both the text of the documents AND the meta data would require entering a citation both in this field and the keyword field simultaneously.
• Statutory citation - See reg citation comments.
• Issued date - During usability testing, users expressed some confusion about whether or not it was necessary to enter both a beginning date and an ending date for the date filters: https://github.com/18F/fec-testing/issues/46. The result of this confusion was some mistrust of the results ("Is the system searching as far back as possible? How far back does it go if I don't enter a start date? If I don't enter an end date, does it default to today?") Some helptext might address this.
• Request date - See comments about issue date.

[AmyKort]

Looks good to us. Thanks!

[AmyKort]

Spoke too soon (again). Let's give it another day before we commit.

[nickykrause]

👌 @AmyKort I'm open to thoughts on this, of course, so feel free to drop discussion here if you'd like! Otherwise I will await your comments 💬

Also, in case it aids in the deliberation, I was shying away from adding helptext to every item for the following reasons:

1) It may needlessly clutter the screen with help icons when we don't yet have data to suggest that those icons are needed;

2) It may convey the impression that the system is more complex than it really is (i.e., prompting thoughts like: "Why are so many help icons needed to use this thing?"); and

3) We can always add helptext later, if the user need appears pressing

[AmyKort]

One comment: On the Issue date and Request date, the testers (2 I believe) said they are uncertain when the first AOs originated, so do not know how to get the whole population from beginning of time, or first 10 years, and wanted some sort of notation as to when the first AO was.

And one question: do we have an estimate for when entity type and role will be added to the search?

[nickykrause]

Thanks @AmyKort!

About entity type and role:

The SAOS system had fields for entity role, entity type, and entity name, as shown here:

However, the only time the entity type field is enabled in SAOS is when the entity role of Requestor is selected. So, it appears that entity type only becomes available for searching when the user is looking for requestors.

On the beta site, we do have Requestor Name and Requestor type, which allow users to search for specific requestors of specific types, similar to SAOS. We also have an Entity Name field that allows users to search for specific other people by name (counsels/representatives, commenters), although it does not specify what type of person they are.

We did not yet build (or plan) for the ability to search solely by entity role (e.g., to search "show me all AOs that have an entity role of commenter"), because we are not quite sure what user need that is meeting, and it didn't come up in the research as a valuable field.

I am not sure if this explanation is helpful. Is there a need that the current fields aren't meeting? If so, let's discuss! (Also, if there are capabilities that seem to be missing, it would be helpful to have an example or two of what the users are trying to accomplish that is not possible currently.)

[AmyKort]

Super! I spoke with Cheryl and I think we'd like to address the entity type issue at our next meeting. On the current site, the entity role can be one of 3, chosen via drop down in SAOS: Requestor, Commenter, and Counsel/Representative.

In any case, I am mucking up this issue with other questions. I think we only had the one comment about help text. Thanks so much!!

[nickykrause]

Okay, I drafted some helptext and collected very useful input from @jameshupp about the copy.

Below is the draft of possible helptext that we have come up with, with a couple of questions ❓ and thoughts 🤔 for our FEC friends to consider ( @AmyKort ):

---

Keyword Search for keywords (including names and citations) within the text of AO documents. Word stems are automatically matched, so searching for a word like “reporting” will give you results for “reporting,” “report,” “reports,” and “reported.”

Select from the document type list to select the types of documents that will be searched for the keywords you enter in the keyword field.

Some older documents were not created digitally and were later scanned to digitize them. For these documents, scanning issues may restrict keyword matching.

🤔 Thought here: We are debating whether or not to be more specific about why the scanning may affect keyword matching (and how)

---

Document type Document types that are selected here will be included in a keyword search. For example, if only the Final Opinion box is selected, then a keyword search will only return results from Final Opinions. Selecting more document types will expand the search to include more documents.

---

Regulatory citation Enter regulatory citations (such as 114.11) to search for advisory opinion cases where those regulatory citations appear.

When the FEC adds advisory opinions to its search system, an automated process finds as many legal citations as possible in the case documents and collects the citations into a list. This list is then linked to the AO case as “meta data.” If you enter a citation in this field, the system will scan the meta data of all AO cases to find citation matches.

To instead search through the text of AO documents, use the keyword field. To search for citations as thoroughly as possible, search for a citation in both places.

Note that for many older AO documents that were not created digitally, the citations can be difficult to identify, and so they may be missed by the search system.

🤔 We know this is a bit long and have some concerns about how this will display on a mobile device. However, we know that this helptext is meant for advanced users who will be seeking details about how this search is working, so we're hesitant to remove some of the info.

---

Statutory citation Enter statutory citations (such as 30101) to search for advisory opinion cases where those statutory citations appear. You can enter citations using either the Title 2 or Title 52 format.

When the FEC adds advisory opinions to its search system, an automated process finds as many legal citations as possible in the case documents and collects the citations into a list. This list is then linked to the AO case as “meta data.” If you enter a citation in this field, the system will scan the meta data of all AO cases to find citation matches.

To instead search through the text of AO documents, use the keyword field. To search for citations as thoroughly as possible, search for a citation in both places.

Note that for many older AO documents that were not created digitally, the citations can be difficult to identify, and so they may be missed by the search system.

🤔 Same thoughts as before regarding Regulatory citations.

---

Issued date The “issued date” for an advisory opinion is the date when the Commission issued its official advice in response to a given advisory opinion request.

The issued date fields will limit a search to show only those AOs that have specific issued dates, or a range of issued dates.

Enter either a beginning date, an ending date, or both. If no beginning date is entered, all AOs will be searched, back to the first AO issued in 1975. If no ending date is entered, the system will search for AOs issued as recently as today.

❓ What date should we put in as the earliest possible date? Is "the first AO issued in 1975 okay? Also, what about the ending date? Is it accurate to say that the system will search "for AOs issued as recently as today"? We are thinking that may be inaccurate if there is any delay between issuance and publication in the online system.

---

Requested date The “request date” for an advisory opinion is the date that the request was first made public by the FEC.

The request date fields will limit a search to show only those AOs that have specific request dates, or a range of request dates.

Enter either a beginning date, an ending date, or both. If no beginning date is entered, all AOs will be searched, back to the first AO requested in 1975. If no ending date is entered, the system will search for AOs requested as recently as today.

❓ Same questions/comments as Issued date.

---

For some additional context, here is how this info might look when folded into the design:

---

Questions, comments? @AmyKort

[nickykrause]

Hey, @AmyKort - I know there's a lot going on with the flip, and this issue doesn't seem very urgent, but I thought I'd page you on this issue nonetheless. Feel free to ignore if other, higher priority issues are demanding your attention!

[AmyKort]

This looks good to me. I'll share it with FEC folks to see whether anyone has answers to your questions or other edits. Thanks!

[nickykrause]

Great! Thanks!

[AmyKort]

One early comment: for statutory citations, that would include references to Title 26 as well, right?

[nickykrause]

Yes! Good point. We can add that.

[nickykrause]

calling @AmyKort :phone: -- just checking if there are any more notes to share about this helptext. I know you said there may be a lot 📚, but I wondered if those comments are yet in a place to share?

[AmyKort]

Not yet, sorry. I don't think we're going to have our answers in time to make progress during this spring.

[nickykrause]

@AmyKort okay good to know. @noahmanger - do you think we should keep this in my pipeline or move it to the backlog temporarily?

[AmyKort]

ha ha! I meant sprint--not spring. that would be an alarming bit of pessimism :)

[noahmanger]

I'll move to the backlog and we can revisit for the next sprint.

[nickykrause]

@AmyKort I am just seeing this issue sitting here in the backlog -- I forgot about it completely! We backlogged it awhile ago in order to prioritize other things, and we just never picked it back up.

I know that you sent me a list of comments from the legal folks that have yet to be incorporated into the helptext. So, if we want to push this ahead after I'm gone, that document will need to be considered.

Also, the helptext we had drafted for the keyword field will likely need to change to accommodate the functionality we are adding for boolean search.

(cc @noahmanger )

[AmyKort]

Got it! Thanks @nickykrause !

[AmyKort]

Issue moved to 18F/fec-cms #1586 via ZenHub