The Journey of a Byline

Slide 1

Slide 1 text

Alice Bartlett - Sta ff Plus, London, June 2023 The Journey of a Byline

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

The Financial Times is the world’s leading paper on business and economic news

Slide 4

Slide 4 text

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.

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

PART 1: THE JOURNEY OF A BYLINE

Slide 7

Slide 7 text

You can read an FT article in many places… FT.com FT App FT Edit E-paper Apple news*

Slide 8

Slide 8 text

Our main character Oscar O’Reilly Fictional Financial Times Journalist

Slide 9

Slide 9 text

What is a byline? A line of text that tells you who had a significant role in creating the article.

Slide 10

Slide 10 text

What is a byline? Link to author page

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

THIS IS SPARK, OUR CMS

Slide 13

Slide 13 text

THIS IS WHERE WE TYPE THE BYLINE

Slide 14

Slide 14 text

What is a byline? Link to author page

Slide 15

Slide 15 text

What is a byline? Bylines are typed by hand into the Financial Times CMS (called Spark)

Slide 16

Slide 16 text

The Destination FT.com FT App

Slide 17

Slide 17 text

Lets take a closer look at these two… FT.com FT App

Slide 18

Slide 18 text

Lets take a closer look at these two… FT.com This is hyperlinked FT App This one isn’t

Slide 19

Slide 19 text

Lets take a closer look at these two… This is a bug!

Slide 20

Slide 20 text

There is something else though, can you spot it?

Slide 21

Slide 21 text

There is something else though, can you spot it?

Slide 22

Slide 22 text

Sometimes we render this as a curly glyph… Hi!

Slide 23

Slide 23 text

But sometimes… it’s this guy Greetings.

Slide 24

Slide 24 text

Let’s talk about curly quotes “Hello” ‘Oh yay’ "Hell no" 'No way'

Slide 25

Slide 25 text

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.

Slide 26

Slide 26 text

Is one of these technically correct?

Slide 27

Slide 27 text

BEYONCÉ

Slide 28

Slide 28 text

O’RIELLY VS O'RIELLY

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

WHY IS THIS HAPPENING?

Slide 31

Slide 31 text

What is happening Although these are both HTML and CSS the code to render them is di ff erent

Slide 32

Slide 32 text

What is happening And there is a bug in one version, and not in the other

Slide 33

Slide 33 text

Video?

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

The destination FT.com FT App

Slide 36

Slide 36 text

Isn’t this all a bit… minor?

Slide 37

Slide 37 text

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.

Slide 38

Slide 38 text

We have six content types 📰 Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages

Slide 39

Slide 39 text

… and they all have content features within them 📰 Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg , etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote …etc…

Slide 40

Slide 40 text

📰 Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg , etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote …etc… … and they all have content features within them

Slide 41

Slide 41 text

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 , etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote …etc…

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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.

Slide 44

Slide 44 text

So, we have a system that has grown over time and gotten a bit unwieldy. What did we do about it?

Slide 45

Slide 45 text

PART 2: WHAT WE DID TO IMPROVE THIS

Slide 46

Slide 46 text

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.

Slide 47

Slide 47 text

We started by trying to understand the system MYSTERY??? **tippy-tappy** **consuming award winning journalism**

Slide 48

Slide 48 text

And all of it has stuff within it 📰 Articles 🔊 Audio 📹 Video 📦 Packages 👩💻 Live Blog 👩💻📦 Live Blog Packages 👩💻 Bylines 🏷 Tags (eg , etc) 🔗 Links 🖼 Images 🔝Toppers (headers) 🍽 Tables 📜 Scrolly-telling 📹 Video 🗣 Pull quote 👨💻 Headshots …etc…

Slide 49

Slide 49 text

We started by trying to understand the system THIS IS A LOT OF WORK

Slide 50

Slide 50 text

We started by trying to understand the system Eventually a pattern emerged

Slide 51

Slide 51 text

We arrived at some principles 1. Transforming 2.Augmenting 3. Rendering

Slide 52

Slide 52 text

We arrived at some principles 1. Transformations in one place 2.Augmentations in one place 3. Rendering in one place

Slide 53

Slide 53 text

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.

Slide 54

Slide 54 text

- Jennifer Aniston “Here comes the science”

Slide 55

Slide 55 text

We built four things 1. A schema for describing content types

Slide 56

Slide 56 text

We built four things 1. A schema for describing content types 2.A new API for content

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

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

Slide 59

Slide 59 text

Our three layers 1. Transforming 2.Augmenting 3. Rendering

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

Slide 64

Slide 64 text

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

Slide 67

Slide 67 text

Slide 68

Slide 68 text

Slide 69

Slide 69 text

FT.com and apps We reintroduced this bug for everyone

Slide 70

Slide 70 text

Slide 71

Slide 71 text

FT.com and apps But we were able to fix it in a single place

Slide 72

Slide 72 text

Slide 73

Slide 73 text

PART 3: SOME PRACTICAL TIPS

Slide 74

Slide 74 text

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.

Slide 75

Slide 75 text

Ask for what you need and be prepared to negotiate, or drop the initiative, if you aren’t able to get it.

Slide 76

Slide 76 text

Give people a problem to solve, not a solution to implement

Slide 77

Slide 77 text

Comms comms comms

Slide 78

Slide 78 text

Tanya Reilly - The Sta ff Engineer's Path

Slide 79

Slide 79 text

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

Slide 80

Slide 80 text

A book about communicating ideas by Giles Turnbull

Slide 81

Slide 81 text

The Agile Comms Handbook Giles Turnbull How to clearly, creatively work in the open A book about communicating ideas by Giles Turnbull

Slide 82

Slide 82 text

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

Slide 83

Slide 83 text

The layer cake of comms The context - this is the hard bit - it’s not the usual engineering work (that’s the detail layer)

Slide 84

Slide 84 text

Our Lure “We’ve simplified the way we render our content, making it easier to add new products to and maintain.”

Slide 85

Slide 85 text

Weeknotes for the context layer “Irreverent, short, with pictures”

Slide 86

Slide 86 text

No content

Slide 87

Slide 87 text

Little videos for the context layer The value of an architecture diagram is partly in the actual act of drawing it

Slide 88

Slide 88 text

Decision docs in the detail layer Document WHY as much as possible. Why typescript? Why HAST? Why a monorepo? Why GraphQL? Why CommonJS? Etc

Slide 89

Slide 89 text

Blog posts in the detail layer Get the team to blog things they are learning as they go

Slide 90

Slide 90 text

— Our CPO “if all teams [communicated] as API rationalisation did … that’s the goal”

Slide 91

Slide 91 text

SUMMARY 1. Little things can tell us big things about our systems

Slide 92

Slide 92 text

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

Slide 93

Slide 93 text

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

Slide 94

Slide 94 text

https://medium.com/ft-product-technology/unspaghettiing-ft-coms-content-pipeline-be1421a434cb

Slide 95

Slide 95 text

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