Project: Linear topic pages

[JoeHasell]

One-liner

Convert a list of ~50 ‘old-style entries’ to Gdocs and publish them using a new article-like format type – the 'linear topic page'.

Project

Why?

This year we've made a huge D&R investment to convert 'old-style entries' into modular topic pages that link out to different parts of our work. The D&R workflow for this topic process combined a design upgrade with a deep content and data review. To some extent, the connection there is unavoidable: shifting from the article-like format of old-style entries to the modular design of topic pages drags us into a full content review.

Conducting such D&R content overhauls is time-consuming work. We would like a more express pathway to get the bulk of the remaining old-style entries into our new design style and into GDocs, without thereby requiring a content overhaul. The aim is to:

• make a rapid improvement to the look and layout of these old-style entries, benefitting from our new design style
• get this content into GDocs thereby:
  • making subsequent improvements to the content easier for authors (thanks to the user-friendly editing/collaboration GDocs offers)
  • getting us one step closer to fully transitioning from Wordpress

Required features / in scope

✅ Get the content into Gdocs, resolving as many formatting issues, bugs, missing blocks as possible along the way
✅ All content should be moved to single-column layout.
✅ Republish the pages as Gdocs
✅ The GDocs can be prepared using a mixture of automated conversion and manual fixes in the GDoc itself (these should be made by the engineer, rather than left for authors)

Rabbit holes/out of scope

• Missing features
  ❓GDocs may be missing some features, and we might have to implement them. Some of these could be lengthy or uncertain projects in themselves.

  ➡️ Overall, aim to do as much as possible whilst getting the 50 pages published; defer special pages or complex/atypical features to the end or skip them. Hannah can give input on prioritization there.

  ➡️ Some steers on particular features already agreed on:

  • ❌ No need for side nav
  • ❌ No need for sub-menus within H2 header blocks
  • ❌ No need to show the summary section expanded by default (possibly we may want to just delete these sections in automated way – but that’s something to figure out with Hannah)
  • ❌ No special component is needed to show links to related articles or topic pages at the top of the page. Such links are often included by authors, usually just as bullet-point lists of hyperlinks or prominent links. Either is fine and the presentation can largely be left up to authors.
  • 👌 We can use a standard All-charts block (not a collapsible one) – this should go at the bottom of the topic page. Possibly, we may want a new component to signal at the top of the article that that block is there down below. But this needs P&D thinking and is a nice-to-have.

• Header design
  ❓We may need some additional design around the page header, to fit better with this content type and separate it from the article design.

  • ⚠️Do we need any more design work here?

• Topics with subnav or country-profiles
  ❓These are especially complicated and uncertain cases, that would require specific investments and more discussion with D&R to work out what we want to do.

  • 👌 There are none of these in Ed’s list

• Degree of investment in auto-conversion
  ❓Doing things in a more automated way (relying on fewer manual fixes in the GDoc) may have future benefits for the conversion of articles moving forward. But this may slow down the project or risk blow-out.

  • 👌 Ike and Hannah are free to optimize however they like there, but with the very hard constraint that the ~50 docs should be published this cycle.

[ikesau]

Here's the remaining work. We have about 8 more days to try and get all this done and merged, before I'd want to be started on the manual part of the process, plus some number of days for design feedback with Marwa.

Adding support for tables and nested lists might be a bit tight. If I had to choose only one to implement, I think I'd go with tables, as nested lists can be rewritten.

Remaining tasks:

Should be fixed in code

• citation notes in the header
  • currently it's just the title and author(s) - we need the "Cite this work" and "Reuse this work freely" links
  • surprisingly annoying to do, as we're reusing the topic page header, which doesn't include this text (because it's written in the sticky nav instead.) I'll have to add some sort of hacky fork in the logic to get it to show up only for linear topic pages. 😭
• horizontal rule
  • easy to do
• add a link to the all charts block when appended to the bottom of the page
  • There are a few ways we could try to do this, ideally one that doesn't require a large restructuring of our (already quite unwieldy) intro section. As an MVP I could just add a regular anchor link to the bottom of the first paragraph. (See Figure A) and if we have spare time I could polish it up a little.
    • An alternative would be to add it to the Summary ToC, though I worry that people might not see it then.
• advanced tables (example)
  • I would like to do this, because we need it for existing articles too. Probably a couple days' work, plus review back and forth, migrating old tables, etc. (PR here)
• nested lists (example)
  • Same as tables
• Some pages are missing their all charts block still
  • This is just a bug. There are probably more bugs that I'll find as I continue to test pages more granularly.

Should (probably) be done manually

• updating links in Gdocs to be links to Gdocs, not full OWID urls
  • while this is, in some sense, a good case for automation, there are a lot of unknowns whereas it would probably only take 2-3 hours to go through each entry and manually update all their links.
• Edit and standardize headings (in cases where the section headers aren't needed now that we're not showing the section's contents)
  • Most of the decisions here will be fairly subjective, not really possible to automate.

Figure A:

[larsyencken]

🎉