Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The Journey of a Byline

The Journey of a Byline

A talk given at Staff Plus in June 2023

This talk covers a small bug with how FT.com renders bylines, and what it tells us about our architecture, and how we fixed the bigger issue. It includes some ideas about how, as staff plus engineers leading big pieces of work like this involves communication and collaboration.

Alice Bartlett

June 30, 2023
Tweet

More Decks by Alice Bartlett

Other Decks in Technology

Transcript

  1. I’m Alice Bartlett I’ve worked at the Financial Times for

    20% of my life I’m a Principal Engineer in the team that looks after FT.com and our Apps
  2. Disclaimer about how much I love my colleagues In this

    talk we’re going to look at a system, and that system was written by people. This talk is not a criticism of the decisions made by those people. They all made sensible decisions based on the information available at the time. However all systems tend towards entropy so this talk is about how we tidy up that system.
  3. In this talk we will cover 1. The journey of

    a byline, including a tiny bug 2. What we did to make that journey smoother 3. Some practical tips to help you with your own architectural challenges
  4. You can read an FT article in many places… FT.com

    FT App FT Edit E-paper Apple news*
  5. What is a byline? A line of text that tells

    you who had a significant role in creating the article.
  6. Examples of bylines Martin Wolf Lionel Barber and Guy Chazan

    in Berlin George Parker, Chris Giles and Ian Smith in London and Sebastian Payne in Bali Cornelia Lauf. Photography by Marina Denisova Mi r­ anda Green is the FT’s deputy opi n­ ion editor. Robert Shrim s­ ley is away
  7. What is a byline? Bylines are typed by hand into

    the Financial Times CMS (called Spark)
  8. Lets take a closer look at these two… FT.com This

    is hyperlinked FT App This one isn’t
  9. Deep dive: curly quotes Straight quotes come from typewriters. In

    printing however you have more quotes to mess about with, and straight quotes are only used rarely. Most OS’s will replace a straight quote with a curly one.
  10. What is happening Although these are both HTML and CSS

    the code to render them is di ff erent
  11. What is happening And there is a bug in one

    version, and not in the other
  12. So we are repeating work The Article page normalises all

    of the apostrophes to be curly The App API incorrectly assumes the byline will always have curly quotes and only normalises the meta data quote
  13. The main problem isn’t the bug The main problem is

    that we are repeating work that we don’t need to. The bug illustrates this because if we weren’t repeating the work, then we would see the bug on FT.com and the App.
  14. We have six content types 📰 Articles 🔊 Audio 📹

    Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages
  15. … and they all have content features within them 📰

    Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg <strong>, <em> etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote …etc…
  16. 📰 Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live

    Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg <strong>, <em> etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote …etc… … and they all have content features within them
  17. And they all have to be rendered in different places

    FT.com FT App FT Edit E-paper 📰 Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg <strong>, <em> etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote …etc…
  18. MVP (Minumum Viable Problem) Demo Curly quotes are the tip

    of the iceberg. We have these kinds of violations all over the place in our article rendering pipeline
  19. MVP (Minumum Viable Problem) Demo And it’s because this system

    has grown over time, people have jammed new bits in where they thought they should go and it’s all gotten a bit… messy.
  20. So, we have a system that has grown over time

    and gotten a bit unwieldy. What did we do about it?
  21. We formed a temporary team Formed a small team of

    people with deep knowledge of our existing rendering code and a desire to improve it! Gave them six months and a fairly open brief: Simplify the way we render our content, make it easier to add new products to and maintain.
  22. And all of it has stuff within it 📰 Articles

    🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg <strong>, <em> etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote 👨💻 Headshots …etc…
  23. We arrived at some principles 1. Transformations in one place

    2.Augmentations in one place 3. Rendering in one place
  24. We arrived at some principles Instead of normalising (or not!)

    Oscar O’Reilly’s apostrophe in every front-end that renders the byline, we’re going to fix that in a single place upstream.
  25. We built four things 1. A schema for describing content

    types 2.A new API for content 3. A helper library for querying the API
  26. We built four things 1. A schema for describing content

    types 2.A new API for content 3. A helper library for querying the API 4.A new library for rendering content
  27. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT article page FT App FT App API Elastic Search [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID FT.com and apps
  28. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT article page FT App FT App API Elastic Search [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID TRANSFORMING FT.com and apps
  29. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT article page FT App FT App API Elastic Search [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID AUGMENTING
  30. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT article page FT App FT App API Elastic Search [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID RENDERING FT.com and apps
  31. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT article page FT App FT App API Elastic Search [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID
  32. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT App API Apollo GraphQL Server [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID UI Library GraphQL Client UI Library GraphQL Client FT article page FT App TRANSFORMING
  33. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT App API Apollo GraphQL Server [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID UI Library GraphQL Client UI Library GraphQL Client FT article page FT App AUGMENTING
  34. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT App API Apollo GraphQL Server [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID UI Library GraphQL Client UI Library GraphQL Client FT article page FT App RENDERING
  35. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT App API Apollo GraphQL Server [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID UI Library GraphQL Client UI Library GraphQL Client FT article page FT App
  36. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT article page FT App FT App API Elastic Search [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID
  37. Reads an article via the website or one of our

    apps Content & Metadata Manages the content and associated metadata and makes it available via APIs FT.com and apps FT App API Apollo GraphQL Server [Other front ends not shown] • Apple news • AMP • FT Edit Requests content by UUID Requests content by UUID Requests content by UUID Requests content by UUID UI Library GraphQL Client UI Library GraphQL Client FT article page FT App
  38. How did we do this Formed a small team of

    people with deep knowledge of our existing rendering code and a desire to improve it! Gave them six months and a fairly open brief: Simplify the way we render our content, make it easier to add new products to and maintain.
  39. Ask for what you need and be prepared to negotiate,

    or drop the initiative, if you aren’t able to get it.
  40. Who are we trying to communicate with? • Other engineers

    that will be using this • Product, design, delivery, research • Upstream teams (Spark and Content and metadata) • Our future selves
  41. The Agile Comms Handbook Giles Turnbull How to clearly, creatively

    work in the open A book about communicating ideas by Giles Turnbull
  42. The layer cake of comms The lure —a tweet length

    summary of what is going on The context — a blog post, an email, a little video. Tell people enough, but not so much that they don’t have time to read it all The detail — stu ff only people elbow deep are going to care about - the tables, the architecture diagrams, the decision docs
  43. The layer cake of comms The context - this is

    the hard bit - it’s not the usual engineering work (that’s the detail layer)
  44. Our Lure “We’ve simplified the way we render our content,

    making it easier to add new products to and maintain.”
  45. Little videos for the context layer The value of an

    architecture diagram is partly in the actual act of drawing it
  46. Decision docs in the detail layer Document WHY as much

    as possible. Why typescript? Why HAST? Why a monorepo? Why GraphQL? Why CommonJS? Etc
  47. Blog posts in the detail layer Get the team to

    blog things they are learning as they go
  48. SUMMARY 1. Little things can tell us big things about

    our systems 2. To fix the big things, you need a team who isn’t looking at anything else
  49. SUMMARY 1. Little things can tell us big things about

    our systems 2. To fix the big things, you need a team who isn’t looking at anything else 3. As a sta ff plus engineer e ff ective comms is part of your job
  50. People who had a significant role in this work Alice

    Bartlett, Rowan Manning, Kara Brightwell, Arjun Gadhia, Ashoor Namrood, Chee Rabbits, Rowan Beentje, Charlotte Payne and Malcolm Moore in London, Maggie Allen in Bangor, Dimitar Terziev in Sofia, and Nayana Shetty and Nick Ramsbottom in absentia