The impossible art of making everyone happy

Okay, yeah. So uh hello, I'm Matt. Uh I've been a core developer on Wagtail from the start, and you might also know me from GitHub or Stack Overflow as Gasman. So a couple of months ago we got an email to Wagtail's security issue reporting email account. It's fair to say that the emails we get there are a bit of a mixed bag. Sometimes you get a well-thought out, detailed description of an issue. Other times it's a someone who really wants to get their hands on a bug bounty, which isn't really something we do, and they're raising alarm bells about some hypothetical situation like If an editor creates a million pages, you might run out of disk space, and this is a security hole, and you need to fix it.

So, but we do take all uh all of these reports seriously because you never know how and when the next legitimate uh really gnarly s security issue is going to show up. This particular email pointed out that in an out-of-the-box installation, an ordinary editor could upload an HTML file as a document and anyone visiting it at its direct URL. would execute any JavaScript code in it which might include like malicious code like a cross-site scripting attacks And at first glance this seemed like one of these um issues that we can just hand wave away in a million ways. So like normally we wouldn't link to a document direct URL like that because we have the uh

document serving endpoint uh which doesn't s suffer from that vulner vulnerability because it downloads the file rather than displaying it in the browser. But then again, we aren't rigorous about uh about telling people you have to lock this path down, because for most people it's no big deal if they're just making a few PDFs publicly available, then there's no harm in that. And we don't want to make deploying and hosting Whitetail more complicated than it is already. Another response we could say is, well, if you're giving someone editor access to your Wagtail site, you're kind of implicitly trusting them not to publish anything evil. But that argument doesn't really fly either because uh in other places we are going to a lot of trouble to make sure that ordinary editors can't just

inject arbitrary JavaScript in into the site. So, okay, what can we do about this? Well, okay, we can easily block HTML files from being uploaded as documents in the default uh setup. But wait, what about other file types that could have JavaScript in them, like SVG? People are actually legitimately uploading SVG files as documents. So all of this puts us in a bit of a quandary. Normally if we get a security issue, we can easily say, yes, that's a legitimate issue. This is how we're going to secure things and this will make it better for everyone. And this time we couldn't really do that. Because naturally when we're pitching Wagtail

to places like Google, the NHS, NASA. who have a huge editor base and need a tight security policy to lock down what editors can and can't do. We want to be able to tell them, yes, we're secure by default. Uh we'll prevent users from uploading malicious scripts But for the hobbyists, like the the bloggers, where it's just one person coding the site, maintaining the server, writing the content, uh securing things against malicious editors. It's not just a non-issue. It's actively hostile to what they want to do, letting them do uh the the things they want. They they can reasonably say, well, I own this server, I could Uh I could place an arbitrary HTML file

on it anytime I want to. And the whole reason I have Wagtail installed is because I want to do this more easily. But now you're wanting to protect me from myself? So this is probably the most direct case we've seen of uh the the needs of corporate enterprisey users of Wagtail being directly at odds with the sort of casual hacker, the casual tinkerer, the the one-man shop. But this is really a theme that's been running right through the history of Wagtail. So one of the principles we founded Wagtail on in the early days was that any complexity would like emerge on demand, any feature that added complexity to the UI. would get out of your way up to the point where you actually needed it.

So for example, if your site is small enough that you don't need collections to organize your images and documents. Then the whole concept of collections is hidden from the UI. That option just doesn't show. It's only once you create your first collection that then that's introduced to the UI. In this case, this is quite an uncontroversial stance, and it's one that's been quite easy to stick to throughout the history of Wagtail without too much bother. In other places we've been a bit less successful at upholding that principle. So take multi site support There's plenty of Wagtail users who make extensive use of it. Caltech in particular have like several hundred faculty sites all on one central Wagtail instance.

But there's also plenty of whiteel users who don't use it. And in hindsight, I feel I should have made it an explicit principle that users should never have to go to the site's admin area. uh or even care that it exists, right up to the point where they're creating their second site. And you can see some traces of that idea in things like the page URL tag, which We'll leave out the domain part of the link if uh if you're if you only have one site or you're unambiguously linking within one particular site. So you could happily leave this set to localhost and uh not have to worry about it at all. It would just never show up. But as the feat uh the feature set of Wagtail has grown and we added the API or Facebook share

links or Django started enforcing restrictions on iframes, these are all these odd places where Being able to find out the host name of the current site is something useful and naturally the developer of that feature is is going to look up the site record. They're not going to stop and think, but how do we accommodate people who don't have that set correctly? It j and then it it just becomes a thing that you just have to do. And this is what makes it so difficult to get this human factor of developer experience right, because if you get it wrong it often won't register as wrong from your sort of all-knowing bird's eye view of I'm the developer of this system, I know it's uh uh

back and forth, uh how these components uh all behave and interact So when someone comes on the Wagtail Slack asking why am I getting this disallowed host error on preview, we jump up and go, oh I know this one. You just need to go to settings sites and set the correct host name. And we're all happy because we've solved that person's problem. They're happy because they're problem solved. And it's a much bigger leap to think, wait a minute, why do they need to go into that? Why can't it just work without having to set this? Another example is uh well have you ever wondered like what the deal is with this circle that we show here on pages waiting review? Well, you see, that's because we can define these custom moderation workflows with multiple steps, and that's actually a progress bar showing

the progress through that workflow. And for large-scale Wagtail sites like uh uh so Motley Fool in particular, one of the biggest corporate supporters of uh Wagtail and Django This is a killer feature. They uh if they publish an article that's considered financial advice, that might need to go through legal approval. Or they might have a process that goes, this page was last updated twelve months ago, now it's time to update it for 2024, and that has a different kind of approval. If you need it, this is a great feature, but and it's a big deal for Wagtail that this exists, but I do have to wonder how many Wagtail users have ever seen this progress bar at a state other than zero out of one steps completed.

And again, this is the the difficult part. When Wagtail featured development is driven by these power users, it's easy for these things to sneak in and make things just that infinitesimal bit more obscure and intimidating for the casual tinkerer. And these things over time mount up and make Wagtail into this less intuitive system than it could be. And it's not something that you'd identify as being wrong as such. No one is ever going to say, oh, Wagtail sucks because there's a weird circle here that makes no sense. It's uh like like Tom was saying a bit, these are the sort of details that as developers we have to care about so that uh so so so that yeah the the end users uh yeah d don't.

uh d don't have to care about those details. And maybe we're not always getting that right. So I don't want to get too carried away with ranting about wagtailed bugbears, especially if it's ones that weren't you didn't even notice were annoying until I pointed them out just now. So to turn this into a positive lesson, uh I think as we're forging ahead building the next great wagtail feature, we need to get better at asking this not so intuitive question. What's the impact of this feature on someone who doesn't want it? And sometimes yeah, catering for these different audiences, the people who do want the feature, people who don't, might be more subtle than just hiding the lesser known feat, the lesser used features.

A recent case where we might have have dropped the ball on that was redesigning Streamfields. The thinking was something like, okay, we want to promote Streamfield over rich text as the natural way of doing fluid long form articles. And that means that people should be comfortable having individual blocks for each paragraph and heading and image. And to encourage that, we need to reduce the visual clutter between all of these blocks and make it feel a bit more like Google Docs or Dropbox Paper. So we've tried various things like reducing the outlines of blocks and making the rich text uh uh toolbar into this sort of contextual pop-up thing so that it's not just this big separating bar that's always visible.

And this hasn't been a popular move because I think in the sort of tunnel vision we had to develop this feature, we kind of missed the point that there's a lot of variance in how people want to use Streamfield. Earlier we heard from uh Just and Simon uh about how they're using Streamfield with the blocks within blocks within blocks. And if people are using it for structured uh data entry with lots of nesting or doing page layouts with Streamfield, then they want that clear demarcation between blocks to show what is is nested where. So the developers making these design decisions need an awareness of how people are using this software that goes beyond, I have this problem, this is how I'm going to solve it for me or for my clients.

So to sum it up in one word, I think it would be empathy, being able to put yourself in other people's shoes. How will they feel about this new idea that you're pushing on them? I like to think I'm quite good at this. Maybe it's one of these dubious superpowers where I do better in front of computers than in social situations because I'm always overthinking everything uh everything I say. How are they going to respond to this? But that sort of attitude doesn't really scale. Because as Wagtail has grown and the people uh the ways people use it have diversified so much. It's impossible to account for every possible situation. And I'm often finding myself in this sort of state of paralysis when trying to push through new features. this change oh what if this change isn't so great for

people who are translating technical blueprints into a right left language? Just you just can't yeah keep all of these things in your head and account for them all at the same time. And it also doesn't scale well to new people coming into Wagtail the Project who don't have that history of learning how people are using it. Those of you who've joined the sprints this week and made your first contributions, I salute you because it's definitely a much harder job now than uh well a much steeper learning curve than it would have been to five or six years ago. Because along with all of the technical tooling that hopefully is documented these days, we also have these unwritten constraints that have emerged organically. Oh actually you can't change this code in this way because that will break this particular edge case.

We ha yeah, as I say, we have to care about these i invisible details in the cathedral so that ordinary users don't have to. So here's one tiny change that I made during the sprints this week. I realized that the readme for bakery demo was giving this explanation for why we need this. n file that's actually not accurate. But then once again just fixing the explanation is only one part of the story. We have to think deeper about Well what would a person coming to this documentation actually want to know? So while on one hand we felt it was useful to know uh to explain that this is using this. env p Django. env package But we also have to recognise that this is a tutorial.

We want people to reach their goal of setting the project up with as minimum tangents and minimal derailing as possible. So in the end, we moved this detailed explanation of what this file is for into its own section outside the tutorial part. So it's a just one tiny bit that needs this sort of deep thinking and this kind of thing is where adopting uh Daniela Procedur's Dio taxis framework for documentation has really been a game changer. This identifies these four categories of documentation, tutorials, how-to, explanation, and reference, and what does and doesn't belong in each one. And

so Danielle has taken this uh organically acquired understanding and experience of uh different audiences and distilled that sort of expertise down into this set of principles to follow so that we can say Now, having this kind of explanation about what this pack is doing in the middle of a tutorial, that is objectively wrong. It's that ability to concretely identify right and wrong that we've kind of been missing in Wagtails user experience. So you it's not wrong to have an empty circle in a one-step workflow or to remove uh a border from a screenfield block. Um but yeah, how how do we identify when we're making those sorts of missteps?

In terms of uh the functionality if we change some code and break the way another c a component behaves on a functional level, we have unit tests that can flag that up. But when we break a user's mental model of how something should work, well what's the equivalent of a unit test for user experience? And they say there's uh an XKCD comic for every occasion, and I think this is the right one in this instance. Because over the lifetime of Wagtail, we've developed tools and techniques for identifying and managing complexity in the code at the technical level. But what tools do we have for when that complexity comes from the fuzzy human factor?

And I think that's the next big challenge for Wagtail. Thank you.