search

fecgov / fec-eregs

The Federal Election Commission's web-based application that makes regulations easier to find, read and understand.
https://www.fec.gov/regulations/
Other
33 stars 13 forks source link

Holistically review the canonical pages of legal resources (AOs, MURs, ADRs, AFs) #326

Closed nickykrause closed 7 years ago

nickykrause commented 7 years ago

While investigating a few issues pertaining to legal resources, we have realized that we need to holistically assess the thoroughness and consistency of our designs for the legal resources' canonical pages.

Specifically, as we worked on this issue about the display of Title 2 vs. Title 52 citations, we realized that we had open questions about how citations are displayed in general on our canonical pages.

Furthermore, as we worked on this issue to create canonical pages for ADRs and AFs, it became clear that we may need to adjust our display of certain informational elements that appear in our established design pattern for MURs (e.g., by moving the Disposition information in the Summary into a Votes section, we could possibly resolve this open issue and this open issue).

This issue is therefore intended to tie these threads together and to look at our canonical pages as a collective. The completion criteria includes:

To start this process, I have put together proposed layouts that include adjustments to the existing designs, which begin to address the questions raised this sprint (outlined above).

Those designs are collected in this InVision prototype.

nickykrause commented 7 years ago

For visibility: I'm testing the canonical page designs over in https://github.com/18F/fec-testing/issues/24

Will update this issue further once my conversations with users are concluded tomorrow

nickykrause commented 7 years ago

(cc @noahmanger @jenniferthibault )

Basically, I collected comments from users this week, but I haven't yet organized my thoughts about the impact that their feedback will have on the designs.

Once I get my thoughts together, I will update this issue and will ping @jenniferthibault, so we can collaboratively refine the canonical page designs (to accommodate the user feedback and to address finer points of visual styling).

If I understand things correctly, then this basically means we'll have three components of design work happening for legal resources in the first half of next sprint:

(1) Refining canonical pages (assigned to both Nicky + Jen, I think?) This issue (2) User research + refinement to search results display (again Nicky + Jen?) Issue 1761: UX design of results display for legal resources (3) Sorting out the filters, which we've started for AOs and MURs, but not at all for ADRs and AFs (again Nicky + Jen?) Issue 1797: Design filters for ADRs and AFs

I think that both (1) and (2) will be finished by the end of week 1 of the sprint and could move to implementation in week 2.

Item (3) might take more time.

Does this sound right to you, @noahmanger and @jenniferthibault?

nickykrause commented 7 years ago

Alright. I reviewed the research findings and noted all of them in this issue: https://github.com/18F/fec-testing/issues/24

@jenniferthibault and I can go through that list and discuss how the findings will impact the designs that the users reviewed, which can be seen in this PDF

nickykrause commented 7 years ago

📣 Calling @jenniferthibault: I took a first pass at updating the canonical page designs in light of the user feedback from last week (originally captured in https://github.com/18F/fec-testing/issues/24).

I would appreciate it greatly if you have time to get your 👀 on the new designs, which are likely in desperate need of some visual styling, but also just because your thoughts would be helpful.

ALSO: For documentation's sake (and in case it is of interest to Jen/others), here are each of the pieces of user feedback that came out of the original design review, and how I addressed them:

Point 1: There are MURs that "link" to ADRs, and vice-versa 👤 user quote:

So they say, we’ll keep the embezzlement part of the case, but refer the committee to ADR...if ADR fails to resolve a case, they will sometimes refer it to enforcement.

🤔 my thoughts: This wasn't something that users brought up organically; it was something that we asked about, out of curiosity, and out of a desire to design helpful cross-linking features, where possible. I am thinking we could save this point as an enhancement opportunity (cross-linking), and address it more broadly at that time. For now, I have logged it as an issue in the testing repo: https://github.com/18F/fec-testing/issues/28

Point 2: MURs (not just ADRs) have non-monetary terms 👤 user quote:

Yes - MURs have Non-Monetary Terms. Sometimes we require people to, um - more often than not, it comes up in ADR, but, I’ve had cases, for instance, where someone screws up reporting, where we’ve required people to attend FEC training…They’re not, um, that common, except for Disgorgements and Refunds, but that’s not to say they won’t be in the future. They are common for embezzlers.

🤔 my thoughts: I added Non-Monetary Terms to MURs, within the Penalty section (which is where it appears for ADRs)

Point 3: Interest in having Docs appear higher for MURs 👤 user quote:

I would move up documents, under the summary. Because that’s the thing that I’m going to want to go to first. I know this is used by the public as well, but for our purposes, having the source material further up would be helpful....Order: Summary, Documents, Citations, Votes, Penalty…Participants.

The documents are the most important things. Could be higher....The penalty is the least important to me; it's easy to just get that in the docs.

🤔 my thoughts: I moved Documents up higher for every legal resource type. This actually helped with cross-resource consistency, because we already had Documents toward the top for AOs.

Point 4: Mixed reviews about how Docs should be ordered 👤 user quote:

As far as the order of the docs, I tend to look chronologically. I suppose, if you wanted to see the bottom line, you would want the Conciliation Agreements. But, I would have to think about that.

As far as the way the documents appear, the most important doc is going to be the First General Counsel’s Report, and the Factual and Legal Analysis...Conciliation agreements are less important than the F&LA and GCRs. If there is more than one GCR, I would always look at both.

🤔 my thoughts: For now, I think it would make sense to keep the document order the same as it is in EQS, and then continue to collect feedback from users. So, I didn't make any changes to the design.

Point 5: Low interest in Entity and Participants sections 👤 user quote:

Participants, I wasn’t really sure what that was supposed to bring up - it’s sort of redundant with the Summary

Entities - at first, I thought, is that really useful, but it’s not bad or anything. It might even be useful, if I think about it for a minute. It can’t hurt anything, probably.

🤔 my thoughts: Aside from Citations, this section is listed last on each of the canonical pages. I think we can keep it there for now, as users seemed indifferent to its presence, albeit uninterested.

❓ Question: It is not clear to me if we can use a uniform label for this section, across resource types. It would be nice to say Participants everywhere, if possible, including for AOs (which currently says Entity). However, Entity may be a term of art. The term entity has also been used for our AO filters already, so we'd need to consider consistency there as well. I can follow-up with Jennie, or perhaps Emileigh will know.

Point 6: Mixed reviews of the Subjects field 👤 user quote:

The subject is interesting to me, under Summary. Because I did pull up another case on the beta site, just to see what the subject would be from another MUR...the subject is helpful, sometimes, although the subjects in Law Manager are more helpful. Having those would be ideal, but I don’t know if that’s possible.

I kind of ignore the Subject -- the ones in Law Manager are better. These are often too vague.

🤔 my thoughts: I vote that we leave the subject in for now and continue collecting feedback from users.

Point 7: Praise for the citations that are presented in the Summary, but request that they could be more specific 👤 user quote:

The problem, when you’re listing citations, is that it’s showing just the description of that particular provisional statute. That’s not particularly helpful to us as researchers...Having the citations is both helpful and not helpful. So many cases have the same citations, so if you list the top level, it doesn’t say much...

But, I do like the layout of the respondent table in the Summary information, with the citations there. It’s nice to see the description of the citation next to the numbers — it could be more specific, referring to subsection — but it’s better than having nothing at all. But yeah, the list of subsections that are cited would be ideal.

🤔 my thoughts: This provides more evidence for a research finding that we have already logged: https://github.com/18F/fec-testing/issues/23. Basically, we need to investigate the possibility of linking to subsections within the statute/reg and displaying the headers for those subsections as well. This has broad implications for citation linking throughout the cite, so we can address that issue separately.

Point 8: Internal users suggest that we may not need to show citations by stage of case in Summary 👤 user quote:

The citations for a given respondent is almost always going to be same at the RTB stage and at the close stage, so I’m not sure that it’s useful to show both.

🤔 my thoughts: Based on this feedback, I took the Stage of case column out of the Summary table. Hopefully other users do not miss it. Removing this column significantly reduced the vertical length of the table and its visual complexity.

Point 9: Praise for the translation of citations between Title 2 and Title 52 👤 user quote:

I really like the translation from Title 2 to 52 because I spend a lot of time trying to figure out what the older MURs’ citations are, in terms of Title 52.

🤔 my thoughts: Hooray! No change to the design. Seems like users appreciate this feature.

Point 10: Praise for addition of Citations in this MUR to the MUR canonical page, but concern that it could be complicated to achieve 👤 user quote:

The section… “Cited in this MUR” — that is great. That is something we don’t currently have. The decision on whether to cite other cases and stuff isn’t as much of a standard in enforcement as it is in AOs…we have a problem in enforcement where you might be citing to a case that’s not yet closed, and it shouldn’t be appearing on the public record until it’s closed.

🤔 my thoughts: It seems like this is useful to folks, but it is a feature that does not yet exist. The old system does not store this information (and therefore does not display it). We have captured work related to this feature here: https://github.com/18F/openFEC-web-app/issues/1763, but the completion of that effort probably shouldn't hold up implementation of this round of updates for the canonical page designs. I left this feature in the design file, but I don't think it is required for implementation this round.

Point 11: Praise for plain-language summary on AOs, but concern about the sourcing and feel it should be presented with a disclaimer 👤 user quote:

I think it might be [useful] for unseasoned users. And maybe for the more seasoned users, too, for a quick reminder of what it’s about. For most of us, the little snippet that we get is enough. There is a battle about this, I think - the Summary information is not complete. We probably need to include a disclaimer. Need to make it clear to people that they can’t rely on this alone - they need to read the AO.

🤔 my thoughts: I have added a disclaimer to the design, but the exact wording will need wordsmithing from Emileigh and comments from Amy (I assume) before we can implement.

Point 12: Request to see MURs that cite this AO 👤 user quote:

MURs are really important and often very difficult to find, because of limitations in EQS. At least with the AOs, those are on WestLaw, so I can find those pretty easily. For AOs, if I’m starting a research project from scratch - I’ll go to WestLaw. But, I don’t have that option for MURs. So one feature that would be helpful is if you had an AO you knew was relevant, you could go to that AO, and it would say not only the other AOs that cite back to it, but something like MURs that cite this AO. That’d be a phenomenal way to find out which MURs to look at.

I think that’d be great [having MURs citing this AO]. Anything that allows for cross-referencing would be wonderful.

🤔 my thoughts: This was a feature request by one user, which was then agreed with by another user. I have not included this request as a part of this round of designs, but I have logged it as its own finding to be addressed as an enhancement: https://github.com/18F/fec-testing/issues/25. This is another item that gets to the idea of cross-linking between resources, to the extent that we can.

Point 13: Request to separate the individual recommendations within the Votes table -- meaning, to fix the broken carriage returns 👤 user quote:

On the MUR page, where the Votes are. I think that’s a very helpful feature, having the votes listed. I wonder if it could be listed in 1-2-3. To have each recommendation be its own line, rather than a block of paragraph text, that would be nice.

🤔 my thoughts: The database demo from Jennie revealed to me and Vraj that the old system (into which the Votes info is entered) doesn't handle carriage returns well. So, although each voting session addresses multiple, unique recommendations, the session data comes into EQS as one giant, illegible paragraph (which is ultimately what we have on betaFEC).

For now, I have changed the design file to show the desired line breaks, but I don't know what the technical lift would be to fix this. I have created a separate issue for it: https://github.com/18F/fec-testing/issues/27, and it seems like fixing this should not hold up the implementation of the canonical page designs.

Point 14: Some AFs have more than one document 👤 user quote: No user quote. This actually came up because Jen asked Vraj about it, and he confirmed that there are some very rare AFs that have more than one document.

🤔 my thoughts: The canonical page design had assumed that there was only one document per AF. With this new information in mind, however, I have updated the AF canonical page to show a Documents table, in case there is more than one doc.

jenniferthibault commented 7 years ago

@nickykrause I have mockups! But they are overwhelming to drop here without change-tracking context and I don't want to write a novel here. I'm hoping to use our Design pairing session today to walk through them with everyone, but if we are short on time we also have our 1:1 today.

BUT, one point I wanted to respond to here is you ❓ about if we can use the same word for Entity/Participants across doc types. (Right now, Entity is specific to AO and the rest use participants). I KNOW I asked this of Amy in a GitHub comment steam some time ago but I can't find it, and can't remember the verdict. @emileighoutlaw is your memory any sharper here?

emileighoutlaw commented 7 years ago

Yes! I do remember, although I also can't find the GitHub issue. Amy checked with the attorneys and "entity" is a term of art specific to AOs, and so we can't change it to match "participants," which we use elsewhere.

jenniferthibault commented 7 years ago

The newest set of canonical page designs can be found in this 🖌 InVision.

For folks following this thread, @nickykrause and I have been pairing through these designs, so she's already aware of the changes I'm showing now.

Here are places where the new mockups differ from her 🤔 thoughts above:

Point 4: Mixed reviews about how Docs should be ordered

Nicky previously recommended: We keep the EQS method of grouping documents by document type.

screen shot 2017-01-19 at 7 50 26 pm

We've changed that to: By default listing documents by date so that the general timeline for the case is retained AND offer sorting on the date and document type categories so that both viewing styles can be achieved and compared

screen shot 2017-01-19 at 7 50 44 pm

Other changes we've made between this version & the last version

Next steps Since FEC legal folks have been interviewed about these pages & given feedback that informed these changes, we feel like we can confidently move forward, pending review from @AmyKort (and whoever else you'd like to check specific sections Amy!)

We'd like to start running these by devs for grooming & layout out any remaining pre-implementation tasks early next week, so that we can begin our implementation plan the following week.

That also means that now is a good time to give @emileighoutlaw a heads up for keeping an eye on any content you'd like to review 🔭 Notably:

jenniferthibault commented 7 years ago

Annnd @emileighoutlaw 's response about the Entity/Participant beat my comment! Thanks for remembering that!

nickykrause commented 7 years ago

Fantastic summary, @jenniferthibault! Thank you for documenting our decisions so well!

emileighoutlaw commented 7 years ago

This work is so amazing, Nicky and Jen! Thanks for tagging me in. I have content thoughts, many of which are pretty granular. So let me know if there's a better way to convey this than in the issue?

General

Documents: Across page types, we have a section Document in which we have a table with a column also called Document, which reads to me as Document, document.

Would it be more precise/helpful if the table column were called Name or Title (looking at it, it looks like this is the name of the document)?

AO page

For the citations, how about this language for our headers:

  • This opinion cites these earlier opinions:
  • AO XXXX
  • AO XXXX
  • This opinion is cited by these later opinions:
  • AO XXXX
  • AO XXXX

MUR page

Closing date: When our dates appear outside of tables, we want them to be Month XX, YYYY for readability

Complainant: If the FEC is the complainant, is it possible to add FEC to the complainant name? For example, FEC Reports Analysis Division (rather than just Reports Analysis Division). I think that would give folks who aren’t familiar with the agency structure a clue that the complaint originated inside the FEC.

Election cycle: Do we have control over how this displays? I think 2004 general election; 2006 general election would be clearer. (Also no capitalization)

Disgorgement: I know this is a technical, legal term, but it looks so ridiculous that it makes me lol when I read it. How about glossary definition here, if I can hunt one down?

ADR page

👍 , love it!

AF page

Report type: How about we make Report year/type: be Report year, type: to match the way the result is displayed.

Closing date: Again, Month XX, YYYY for readability

Civil penalty: Readers often have trouble understanding whether / means and or or or and/or. In this case, I think it’s or, so how about we call this table column Civil penalty or fine ?

Tables: This is the first page where I think we tip into too much technical language in our tables (Reason to believe, Treasury referral, etc.). I don’t doubt that those are the precise titles for the columns, but I want to think about ways to provide contextual explanation for users. I don’t have a recommendation yet, but I do want to flag this as an area where I'd like to make some content improvements.

Documents: If we’re doing a button when there’s only one document, I think we consider other button copy. AF 1 | 03/12/2005 is a pretty intense button to click on (and doesn’t convey much helpful information. What does the date refer to, for example?). Would something more generic, like Open case document or Open original document, actually provide more clarity to users?

jenniferthibault commented 7 years ago

Thank you for the thorough review @emileighoutlaw ! Thoughts in line & the 🖌 InVision is updated with blue annotations for questions dependent on dev guidance for us to discuss in grooming next week.

Documents: Would it be more precise/helpful if the table column were called Name or Title (looking at it, it looks like this is the name of the document)?

Yep! Name or title 👍

AO to AO citations This opinion cites these earlier opinions: This opinion is cited by these later opinions:

👍 + ❓ For consistency, should we drop the colon from these two, or add colons to all other categories? Or, should they be different?

Date formatting When our dates appear outside of tables, we want them to be Month XX, YYYY for readability.

Complainant text If the FEC is the complainant, is it possible to add FEC to the complainant name?

Election cycle format Do we have control over how the Election cycle data displays?

⏸ Adding notation for mockups to discuss in dev grooming, but all these make sense to me!

Disgorgement: How about glossary definition here, if I can hunt one down?

It is a funny word! 👍 to 📖 There's a definition in the EQS-specific glossary that might get us started

Report type: How about we make Report year/type: be Report year, type: to match the way the result is displayed.

👍

AF Civil penalty table category Civil penalty or fine

👍

AF Table column names are technical/jargon barriers

Agreed. ⏸ for your recommendations

Yeah this is tricky, because the case document isn't named anything helpful, just AF ###. The date is the date the document is published, which may be helpful context hinting (which is lost when the table isn't shown, the most usual scenario. Only 33 cases have more than 1 doc, 2882 have exactly 1) Maybe an arrangement like this?

screen shot 2017-01-20 at 3 33 39 pm

❓ Did you get a chance to peek at the AO disclaimer for FEC Record Summaries?

Note: This summary is drawn from the FEC Record. It is not official legal documentation and may not contain all the relevant details from this advisory opinion. For a thorough understanding of this opinion, please read the actual case documents.

noahmanger commented 7 years ago

I don't have anything to add, but I wanted to flag this issue as something to perhaps close the loop on https://github.com/18F/openFEC/issues/2125

AmyKort commented 7 years ago

Question about the AO disclaimer for Record Summaries: We don't need to repeat the current disclaimer exactly, but can we get closer to this:

"This publication provides guidance on certain aspects of federal campaign finance law. This publication is not intended to replace the law or to change its meaning, nor does this publication create or confer any rights for or on any person or bind the Federal Election Commission (Commission) or the public."

Rather than saying the summary is not official legal documentation, I think we could say the summary is not intended to replace or supplement the opinion and may not contain all of the relevant details . . .

emileighoutlaw commented 7 years ago

💭 Forgot to mention in our meeting today:

❕ Disclaimer: How about something like this @AmyKort:

  • Note: This summary is drawn from the FEC Record. It is not intended to replace the law or change its meaning. For a thorough understanding of this opinion, please read the case documents.

:person_fencing: I'm still thinking about ways to make in-context content improvements to the Administrative Fine page.

emileighoutlaw commented 7 years ago

Spent some time thinking about in-context content improvements. There are a couple language things I think we can do to improve the understandability of this information:

Reason to believe

What's most difficult about data column is that even if a reader understands that “reason to believe” means The Commission's reason to believe a committee failed to file on time, we're still missing information. The gap here is that when the Commission finds reason to believe, they propose a fine and send a letter to the committee informing them of this.

So what we're looking at in this column seems like two things to me:

First: an amount field, probably called

Proposed fine (this is what it's called in legacy site content)

Second: a date field, called something like

Initial finding

or

Committee notified

That's not to say I 100% think this should stay in a table and be split into two columns. I know Jen is looking at date chronology design stuff. Rather, what's important here I think is that this is two discrete pieces of information.

Civil penalty or fine

We'll have to check with FEC, but calling this something more like Final civil penalty or fine, would clarify the relationship between this and the amount listed under proposed fine.

Treasury referral

This is likely a @nickykrause question — is the amount here ever different than the amount in the Civil penalty or fine column?

nickykrause commented 7 years ago

@emileighoutlaw:

I think is that this is two discrete pieces of information.

Interesting! It does seem that way. I wonder if the data is stored in a way that will allow us to show this. I do like the idea - perhaps we can get clarity in grooming tomorrow.

Also, about this:

Treasury referral This is likely a @nickykrause question — is the amount here ever different than the amount in the Civil penalty or fine column?

I have an ✉️ out to Jennie. I thought about asking Vraj to check (since it is probably fairly a straightforward exercise, technically), but I don't think we have loaded AF data yet, so I wasn't sure he'd be able to answer. Anyway, I will let you know when I hear from Jennie.

(PS: I asked Jennie about the Amount paid field in this last message as well)

jenniferthibault commented 7 years ago

While ✉️ is out, here's how I'm thinking of handling these:

screen shot 2017-01-23 at 7 09 04 pm

I think the RTB date & fine are two discrete types of information, but the proposed fine happens during the initial finding. I wonder if we can combine them into one "phrase" or line item like I did above?

emileighoutlaw commented 7 years ago

I think this design looks amazing!

:pen: I like the impulse for adding more context to Report year and type, but I'm wondering if the more valuable thing we could do is see if our devs could translate the coding (Q2 and 2000) to better align with the way we present the data in our filings section.

So we'd end up with something more like:

Report: April Quarterly 2000

✔️ I'm game for keeping initial finding and proposed fine as a single line item.

:pen: What do you think about rewriting Treasury referral as Referred to Treasury Department?

It's longer, but Treasury referral could theoretically mean a referral to or a referral from. Referred to Treasury Department is less ambiguous. It also seems worth clarifying that we're talking about the Treasury Department and not another government Treasury entity.

💭 We'll probably have trouble adding a glossary definition for "Initial finding," which isn't a term of art (and that's been a major barrier for us in the past). But that got me thinking that this page would be an excellent place to build a pathway to our Administrative Fine Program page. Right now it's written for committees (second-person POV), but we're moving it to the neutral third-person this week! And it explains a lot of what's going on here.

jenniferthibault commented 7 years ago

Thanks for this @emileighoutlaw ! I think we're hitting the limits of what we can think through pre-implementation without expanding the scope of the issue to more new enhancements, so I'm going to hold onto your 💭 and put it in a new issue ( #328) !

The 🖌 InVision is updated with the most recent and complete annotations & questions dependent on dev guidance for us to discuss in grooming today. I think we're in a great spot for grooming these now: we have a good idea of what the design should do in different scenarios, and we need to review with folks who understand the back end data to figure out which scenarios are feasible & most efficient.

Heads up for grooming today @anthonygarvan / @vrajmohan / @dogweather 🔆