Content strategy and design for Wagtail custom/resource templates

[emileighoutlaw]

Right now, we're using the custom page template for our Help for candidates and committees article pages. Unlike the resource page template, the custom page doesn't have a sticky table of contents on the left side:

Custom page:

Resource page:

Adding this sticky page menu to the custom template would make it easier and faster for readers to orient themselves to a page's contents. Many of the Help for candidates and committees custom template pages are very long, like this one:

In fact, even the shortest pages have legal citations that users have to scroll down to find:

So overall I think adding the left-side sticky nav to the custom template would be a boon to our users.

cc @noahmanger and @jenniferthibault

This has been on my mind, but I'm surfacing it as an issue now because it's related to the work @nickykrause and I have been doing on the contact questions.

[noahmanger]

Why not just use the Resource Page template for these pages instead?

[jenniferthibault]

I have some questions about this, because I've been worried about depending on the side menu to solve all the problems of very long pages. Our side nav/table of contents pattern works well for a small handful of items, (~3-6?) but any more and there's a combination of factors that decreases readability & helpfulness. Including

• All caps decrease readability for longer content, so the more items we put, the less scannable it becomes
• We started using this for pages with broad page titles, like "Overview" "Summary" + other things that were 1-4 words. The titles of these pages are often very long phrases that break into two (or three or four!!) lines, which really makes them hard to scan
• When you hit a certain number of items, the nav overflows the page height but sticks, so you can't actually see what's farther down the page, defeating the purpose

So this pattern works well for medium-sized content structures, but not large or XL, as is our case, and we may want to think of something different.

@emileighoutlaw I'm wondering if you've seen other content design/page structure patterns that have solved L+XL content challenges in a different way that we could think about?

I'll poke into visual/UX patterns, but I think it's a combination of approaches

[emileighoutlaw]

So so glad you brought up all these excellent points, @jenniferthibault. Agreed on all.

I'm still very hopeful about something like a table of contents (perhaps in a left sidebar) because it's what I see most frequently in other designs that I admire (Stripe, Squarespace, etc.)

I did some poking around, and I really really like EITI's pattern. (Bonus, it was designed by a human we can actually talk to! h/t Brian Hedberg).

What I like about this:

• The collapsed/expanded view of sections (more detail as you click into or scroll down to each section)
• The "top" feature that jumps folks back to the top at any point
• The condensed version of headers (Fiscal costs of extractive activity becomes Fiscal costs)

One thing I don't love: Their element is on the right side of the page, and it seems like most other folks have similar elements on the left (see also mailchimp and facebook). I prefer the left too, just because it's in a hotspot for eyetracking/page scanning.

[jenniferthibault]

Just to rebump Noah's question— @emileighoutlaw can you talk a little bit about tradeoffs of this approach verses changing these pages to the Resources page template (which does have the nav in place, even if it's imperfect and would need a design tweak)?

[emileighoutlaw]

I think there are a few reasons why the resource template isn't ideal.

The first is that there's no easy way to convert a Wagtail page from one template to another. So making these Resource pages would require us to rebuild the whole section (totally doable, but a few full days of work + also proofing to make sure we didn't mess anything up in our copy/paste journey).

We'd also have to update Wagtail to all us to create resource pages in the Help for candidates and committees section, which we haven't done, yet.

Ultimately, that chunk of work seemed more labor-intensive than updating the custom template to include the left sidebar from the resource template (although that's admittedly based on my very cloudy understanding of how we update templates).

And one other potential snafu: the custom template was tailored so that we could add example blocks of text, link to Record articles, and have the "continue learning about this topic" on the bottom of the page — I don't think those exist in the resource template.

(Aside: We built all these Wagtail templates as we needed them, and so I didn't do a good job of tracking or planning content models. I'm not sure we could have done anything differently at the time we created all these, but the lack of high-level strategy is coming back to bite us a little bit right now. So I'm sorry :( )

[noahmanger]

I see your thinking, but from the technical side, it's not possible to have the side nav generate for a single big chunk of text. You need to be able to identify each section and give a unique ID to each which is then referenced by the navigation. This is what the ResourcePage template is designed to do. Adding those other components to that template isn't that hard.

Before we make any changes though, we should probably step back and think more about the high-level strategy now that we have a better handle on the shape of the content.

[emileighoutlaw]

I see what you're saying. And I agree we should talk through this.

Because it's helpful for me to visualize things, I made a quick and dirty breakdown of what exists on each template, and I feel like I have a much clearer picture of what's going on in each template now.

Do you have any thoughts about how we should keep thinking about this?

[emileighoutlaw]

We've talked this through and think there's a larger, separate issue to be sorted out in the future:

Background: Templates are useful for enforcing structural constraints. Right now we have two main templates that we use for content pages: custom and resource.

Questions: Do we need two templates for (custom and resource)?

• If so— how do we decide when to use which?
• If not— can we combine?
• How do we determine when to make a new template versus using an existing one?

[jenniferthibault]

Noting for future github archeology: This issue has not been addressed and is still causing the same problems described above. This was closed in a batch of issues that have been iceboxed for an extended period of time.