Make a plan for importing various "Reports about the FEC"

[noahmanger]

The "Reports about the FEC" section in "About" calls for several different pages, each of which acts as a feed of the various reports about the agency (IG reports, budget docs, etc.). Many of these are PDFs, with an occasional HTML page.

I'd like to use this issue to:

• Identify all of the reports and where they will live (likely in a spreadsheet)
• Determine what we need to do on the back-end to support these documents
• Determine how we will add them to the system

[noahmanger]

Progress update on a suggested approach over in this PR https://github.com/18F/fec-cms/pull/804

[noahmanger]

@patphongs and @emileighoutlaw I made a new spreadsheet 🔒 that we can use for organizing these reports.

This has columns for all of the fields we need for the import script, it just needs to be filled out. I set up the category column to validate based on the sub-categories available for each parent category.

Can I hand this off to one of you to fill take from here?

[emileighoutlaw]

Want to divvy this up between the two of us, @patphongs ?

[patphongs]

@emileighoutlaw Sure let's look at this together. Let me talk to you about it.

[emileighoutlaw]

⚠️ 💟 Long post warning. Thanks for sticking with me on this 💟 ⚠️

tl;dr I've been working with the spreadsheet of report content 🔒. I think we may need to adjust our design.

Current design pattern:

Date

Title

Link (PDF | size)
[ category tag ]

🎉 Yay! So awesome! But with real content, the fields are regularly repetitive, a lá:

October 3, 2011

Office of Inspector General FY 2012 work plan

Office of Inspector General FY 2012 work plan (PDF | 250KB)
[ work plan ]

😭 Not awesome.

My first fix for this repetition was to tailor the link field to avoid duplication:

October 3, 2011

Office of Inspector General FY 2012 work plan

Open PDF (250KB)
[ work plan ]

🎉 Yay again!
😭 But there are sticky wickets here, too:

• When I ran that idea by our accessibility guild, I learned that screen readers often browse pages in a way where users just hear the link titles. So they'd get "Open PDF (250 KB)" without additional context. Their recommendastion was that we add a .sr-only span in the link that includes the title of the document.
• The nicely tailored "Open PDF" content only works if it's something that happens automatically and isn't a field humans have to fill in. If we leave it up to well-intentioned folks to enter the link information, they'll likely (by accident and with the best intentions) end up creating repetitive link text. Or inconsistent links.

So! That leads me to my questions.

• ❔ Is a way to automatically create a .sr-only span, which includes the document title?
• ❔Is there a way to automatically in the future populate the all links with the text "Open PDF (size)"?

If yes and yes, this seems like a good solution. We can stop here.

If no ⬇️ :

We should probably tweak the design. These feeds are going to house the content folks are least willing and able to adjust by hand. If we set folks up with multiple fields to fill out, we're paving the way for future duplication like this (h/t to Corey M. for sharing this case study from her California work):

That first link to salary scales is a repetition nightmare.

Basically, I looked at a lot of ways that we could tailor this content to make it more friendly to the design. But I think anything that has to be done by hand is going to be a mistake. Instead, I'd recommend we move to a design with fewer fields. Like this one:

The benefit of this one is that we have only:

Date

Title that is also a link (PDF | size)

[ category tag ]

That's a giant bucket full of thoughts I just dumped here. So I'll give you time to digest @noahmanger. Also tagging @jenniferthibault, because this has to do with design. We can discuss in person, if we don't want to keep talking in GitHub.

[noahmanger]

@emileighoutlaw yeah, those solution's aren't tricky at all. We'd just have one field for document title and could include it twice in the template. I think I'd prefer the simpler approach that just shows the title with some indicator that it's a PDF. Though just noting that we won't have the "size" value unless you add it by hand.

[emileighoutlaw]

Cool. If Jen feels good about the solution, I think the best solution might be the most minimal one.

Using this as my guiding light:

And then with real content, the feed would end up looking something like this:

November 15, 2012

Performance and accountability report (reports consolidation act of 2000) FY 2012 (PDF)

[ Performance and accountability report ]

Even with this approach, there's going to be some content repetition, but I still think it's our best option without sinking a lot of time and energy into hand editing document information fields (which I am happy to do but don't think is sustainable long-term).

[jenniferthibault]

My only observation is that I'd like to keep the document icon associated with PDF files — this is how folks can tell which doc links will be a PDF and which will be an HTML page at a glance.

If it's a PDF:

If it's HTML:

[emileighoutlaw]

Our spreadsheet should be totally filled with content now, except for the few documents that we couldn't find dates for!

[emileighoutlaw]

Forgot to ping @noahmanger in ^^

[noahmanger]

Plan made and a new issue made for importing these #828 . I'll make the small change to the layout in a PR.