Making a Splash with your Open Source Project by Russell Keith Magee

Speaker 1: Come on, no. Well

Speaker 2: hello again Philadelphia. Um as as we just said my name is Russell Keith McGee. If you've heard my name before, it's because I've I'm a member of the Django core team and I have been coming up on 11 years now. I've served on the technical review board for the 1. 7, 1. 8, 1. 9 releases. I'm also on the security team. Django is an open source project, but it's not the only open source project I'm associated with. These days I'm mostly spending my time on the BWAR project. BWE is an open source collection of tools and libraries for creating native user interfaces in Python for desktop but also for iOS, Android and single-page web apps. And I've been associated with a bunch of other open source projects over the years as a user, a contributor, and project maintainer. So earlier today I spoke about some of the known and factual aspects

Speaker 2: of open source projects that you need to be aware of, things like legal issues and uh and and and sort of burnout and depression issues. These are well studied, have well-known causes, well-known resolutions, there's all very, very factual stuff there. This talk, however, isn't about that hard data. This is about how to make your project successful. Now the thing that I want to flag here up front is the very distinct risk of cargo cultural. Cargo cults are is a phenomena that came out of World War II. There were a lot of Pacific islands filled with people who weren't modern Western civilizations. And their first experience with meeting Western civilizations was that these people would turn up and these these large metal skybirds would come down and deliver large amounts of food and housing materials. and

Speaker 2: all sorts of vehicles and interesting things. And then a couple of years later they all disappeared again. So they started building these giant bamboo structures to try and bring the skybirds back again. They'd they'd flatten out large pieces of land and and and set burning pyres along the side because they see there was always lights at the side of these uh where these skybirds would land. So we ended up with entire cultures Building landing strips for planes that were never going to come because they didn't understand why the planes were coming in the first place. Cargo cult in technologies can be very, very easy to do. You sit there and you say, okay, I This was this project did this, this project is successful, therefore I must do this. The one thing that I will assert, and I hope it's not too controversial, is you can't be an underpants

Speaker 2: no For those who don't know about underpants gnomes, uh it's a joke from South Park. Uh the underpants gnomes are these little creatures that sneak into your bedroom at night and they steal your underpants. Um why? Because they've got a business plan. Step one, they steal the underpants. Step two Step three, profit. They can't ever explain what step two is though. If you're really, really lucky, you might have a massive success, just accidentally happened to you. But more is more realistically, you're going to have to work at it. And that preparation starts with knowing what kind of project you've created and what sort of what your commitment to that project is going to be Now, I would argue there are two main sources of open source project release. The first is the simple you might find this useful release.

Speaker 2: It's where you're not really looking to start some major project. You're not trying to write the next Django. You've just got a thing that you've done and it's no harm to me if I put it out there and you maybe use it as well. You might find it useful. Who knows? This is essentially the spirit behind the scientific method generally. In the movie Awakenings, it's based on a book by Oliver Sachs, stars Robin Williams. The main protagonist is a researcher. He's been quizzed about his PhD, where in which he describes as an epic project. I was to extract one decagram of myelin from four tons of earthworms. I was the only one who believed in it. Everyone else said it couldn't be done. And his inquisitor says, it can't. And the response is, yeah, I know that now. I proved it. So

Speaker 2: You might not even be talking about a successful project here. It might just be something where you're tinkering to see if something might be viable or it might be something you've used in production but you don't have any particular commercial interest in it, but it's no, you might as well put it out there so someone else can look at it You're not trying to start something, you're just trying to help the community by letting the world know that you've done something that might be used as a starting point or an inspiration or as proof that it just doesn't work. The other approach is where you're throwing things out there and you actually want people to use the project. You're planning to contribute or continue working on it, you'd like other people to use it too, and in an ideal world you get contributions from other people that you could that can improve your code base. This is where you think you've got the next Django in your hands. And it doesn't necessarily have to be something the size of Django. It can be a small project, but you're putting your flag in the dirt to say I'm the go-to

Speaker 2: library for X. But it's incredibly important to know which type of project you're releasing. And if you're just throwing it out there, you're not making a commitment to maintain it, that's fine. But if you're asking people to intellectually invest in your tool, your framework, your library, then you've also just signed up to pay attention to that community. And to be clear, I'm not saying you're therefore obliged to fix their bugs for free. I'm saying that you're putting something out there and representing it as something that you intend others to use. You've just started a dialogue and you've started to set expectations So the key thing here is you need to know what you're trying to do and then communicate what you're trying to do. Communicate your intentions. If you find a project and it says in banner text in the README, this is an experiment that I've abandoned then

Speaker 2: you know what to expect. If it says nothing, the default interpretation is almost always going to be, this person wants me to use their project. So consider yourself as a user. If your project website says retroencabulator is the best framework for prefabulating your differential girdle spring. And you've got a differential girdle spring that needs prefabulating. Um who doesn't? Um you're going to be excited. You've just found a project that solves your problem. And when it turns out that it only prefabulates non-reversible differential girdle springs. You're going to log a bug or try to submit a patch or try to engage with the project in some way. After all, why would this person have put it out there if they didn't want it to improve? And if the project maintainer then doesn't respond or responds slowly or responds ambiguously or worse responds angrily, you're just going to get annoyed at the project.

Speaker 2: And the project maintainer has then just lost a potential community member. Although, as an interesting aside, we would all, as human beings, do a lot better to get in the mental habit of thinking or thinking of open source projects as you might find this useful by default, rather than everybody please use this by default. Assume by default you're gonna get no support unless the project says you will. Don't assume you're gonna get support and then be surprised when you don't. And don't forget, a project can change over time. A couple of years ago I was maintaining a library called Cassowary, which is an implementation of a well-known constraint solving algorithm. I published it because I was at that time using it as part of Toga widget toolkit. I've recently changed Toga to use a CSS-based approach, so I no longer need the capability that Casaweri

Speaker 2: implements. But to make sure there's no confusion over the status of the project, the project website is now listed under an attic section of the BeWare homepage. And at the top of the README, it says the same I'll still merge pull requests and if someone wants to take over the project, they're more than welcome, but I've made it clear that it's not the focus of my attention anymore. So, you know what you're trying to achieve with your project and you've communicated that effectively. What comes next? I would suggest the next thing you need to look at is your project's out-of-box experience. the experience that a new user has when they discover your project for the first time. Imagine someone knows nothing about your project, your code. They visit your website. What do they find? Django's out-of-box experience is a good example here. If you visit Django's website, you're invited to do a tutorial.

Speaker 2: And there's a sorry, there's a brief description of what Django is, and which invites you to do a tutorial. You follow the steps and about the only decision you really need to make along the way is what database you have to use, and even then it strongly says just use SQLite for your first pass. Your path to getting started is clear. You don't have to make a whole lot of decisions. And you should, at the end of a four-page tutorial, get a running project with a decent feel of what the project can do. If users can't find your tutorial, or they can find it and it doesn't work, they're going to assume that either the problem is in them or that they're stupid, and either result isn't good for your project. Kathy Sierra is a tech writer and blogger. She wrote a blog post entitled Attenuation and the Suck Threshold, in which she talks about user engagement on new projects.

Speaker 2: And what she says is when you're introducing a person to a new project You need to make their time from zero to kick ass as low as possible. A new user has to go from I know nothing about this project but the name to kicking a real-world, practical and personally applicable goal as quickly as possible. If that time is low, the U user gets an immediate sense of progress and a little endorphin rush in their brain and they get over that suck threshold. They feel like they can do anything, and they're more likely to persist and go to the next step. Even if those little steps are a little bit harder. And every time that they kick a little bit more ass, they get a little bit closer to doing more and more advanced things. The more likely they are to give up, the more likely they are to develop a

Speaker 2: negative impression of your tool or tool or product. Every decision a new user has to make during the tutorial process is one more thing that could make it harder to get over that sub threshold. Every dead end they go to in your documentation tree makes them feel that little bit more stupid. And they're not stupid. You've just failed to communicate effectively with your most important audience, new users. Marketing people like to talk about conversion funnels because they're going to help us and it helps to think about your open source project in a similar sort of way The use of an open source project doesn't stop with becoming a user. If you're going to have a vibrant, long-running project, you want people to work their way all the way down the conversion funnel. They come to you as potential users. The entire population of the plan is effectively a potential user. Some of those people will do the tutorial and become new users of your project.

Speaker 2: Some of those people will continue to use the project, find some real practical use for it and become actual users. Some of those users will hang around and become long-term community members. Some of those community members will eventually become contributors. Some of those contributors will join your core team and eventually some of them will move into leadership position. Unless you are working on that entire funnel and that entire conversion funnel, your project will at some point stall. That means you also don't just need a first-time user tutorial. You need a first-time contributor tutorial. You need to document your processes and the so the potential contributors can move their way down this process or down this funnel. Django does this fairly well. The contribution process is very well documented and at the sprints there's always a a good

Speaker 2: someone who's leading the process to say, hey, let's get involved. It's something that I think I've been able to do quite well with BWAE so far, with open offers of mentoring and with the challenge coins trying to encourage people to get involved. It's not just about getting users though. You have to be able to retain those users over time, which means you have to think about what users need in the long term, such as the role that backwards compatibility plays in long-term project viability. Django has a backwards compatibility policy which guarantees that code running today will continue to run for quite some time in the future, at least two release cycles, and then there's also a long-term support release to go even longer. Other projects deliberately break uh break compatibility between point releases. How much does this matter? It depends entirely upon your perspective and your intended audience.

Speaker 2: If you spend your life working on short-term contracts delivering sites with no long-term maintenance overhead, say a promotional website for an event or a site supporting an advertising campaign, you don't have long-term problems. You finish a job, you move on to the next one. Every time you start, you're free to try something new, experiment a little bit, replace something that didn't work well last time. You're looking at the world through glasses which think of six months as a long time. However, if you're engaged in a multi-year project, you really care about long-term maintainability. In a former life, I was involved with the Joint Strike Fighter project. It's a multi-billion dollar project to develop the next generation fighter for the US Air Force. And at the point of conception of the project in 1990 They didn't anticipate delivering a working airplane for 20 years.

Speaker 2: And at this point, it's six years late. And before it became operational, they were planning on doing two full rebuilds of the avionic subsystems If you're in this space, you really care about long-term maintenance. You don't want the world shifting underneath you every three months. You can't use a product that doesn't have a 10-year support plan in place. Six months is a rounding error. It's a series of meetings with your supervisor. Another example of this is a quote from Marseille Seglaski from Pinboard. A rule of thumb that has worked for me is that if I'm excited to play around with something, it probably doesn't belong in production. And I agree with him. Excitement is not a property I aspire to when I think about my production servers. Boring is a virtue in production.

Speaker 2: Boring is predictable. Boring doesn't wake you up at three o'clock in the morning having trashed half your database. Now, to be clear, I'm not saying one approach is right and one approach is wrong. I'm saying that the properties you value in a project depends on your perspective. And that perspective is something you need to communicate so that users know what to expect. You also can't just focus on your own project and your needs. You need to look at the broader community, the ecosystem in which your tool sits. To explain this, I'd like to take a quick tangent here and talk about tractors. One of the project founders of Django is a man named Jacob, Jacob Caplan Moss. Fortunately not here this week. Jacob is a man of many talents, but his uh until recently one of his biggest uh passions was his farm and his tractor named Tinkerbell.

Speaker 2: One of the interesting features of farm tractors, not something we usually think of as a bastion of high-tech, but they um uh is this is a feature of something called the three-point linkage. The three-point linkage is a system that has been used on tractors for almost 90 years. It was originally developed in the 1920s by Ferguson and then was adopted by pretty much every farming equipment manufacturer and tractor manufacturer. It was eventually encoded as an ISO standard in the 1980s, but that was really just codifying what everyone already agreed on. What the three-point linkage does is provide a very simple interface that enables plows, seeders, harvesters, whatever else to be attached to any tractor you want. And hitting the backwards compatibility point, it's been consistent for 90 years. A farm tool built in the 1930s will connect to a tractor that came off the assembly line last week, and vice versa.

Speaker 2: What the three-point linkage does is change a tractor from being a single purpose tool into being part of an ecosystem of tools. When you buy a tool, you get a tool. And you can buy a fine set of tools. The real tool power comes when the tools are able to work together. When you buy into an ecosystem, you get infinitely more value because you're not just buying a tool, you're buying into all the possible ways that tool can be combined with everything else in the ecosystem. No tool lives in a world of its own, especially in computing. So pay attention to the rest of your community and work with that community and their expectations. This is really just Metcalfe's law writ large. Django by itself is not that exciting. It can do stuff, sure, but it's limited. What's exciting is the ecosystem of stuff around it. Every time someone writes a plugin

Speaker 2: or a library that's part of the Django ecosystem, Every other package gains some value because it's compatible with all the other bits. There's something like 4,000 packages on PyPI that are tagged as being Django related or Django compatible. Now even if you consider Sturgeon's law that 90% of everything is crap, that's still 400 useful packages. This is something that Django does quite well at a technical level. But it doesn't do it well at a social level. Django's app architecture encourages people to build distributed apps specific tasks. As a project though, Django doesn't do a good job at highlighting those apps in the community as a whole and the community the value that's been added in the community. There are sites like Django packages, but Django's core infrastructure doesn't ever reference those sorts of tools.

Speaker 2: That limits the usefulness of Django packages because it's not a hub that everyone who comes to the project knows about. So if you'll notice, if you're paying attention, what you'll notice is a recurring theme here, the importance of communication. And it's not just a matter of what you're saying, it's how you say it, how the message gets out there. Django wasn't the only Python web framework that was launched around 10 years ago. About that time there was also Cherry Pie, Turbo Gears, Repos BFG. Quick show of hands, ten years later, who's heard of those three? Yeah, so we got maybe a quarter of the audience. Okay, so Turbo Gears and Repos PFG kind of merged and reformed and ended up as pyramid. Why was that rebranding necessary? Well, if turbo gears had been successful, it wouldn't have needed to merge with anything. It would have been the Django of today.

Speaker 2: So why did Django, for want of a much better word, win? Was it because Django is technically superior? Well I've had more than one discussion with pyramid advocates who have told me at great length that Django does it wrong. And let's say they're right. They've certainly got some valid technical arguments in there If that's the case, how did a technically inferior product win? Django, I would argue, won because the publicly communicated narrative about Django was a lot more coherent. It resonated better with the audience that reached. Django's tutorial meant the onboarding experience was was a lot better. Django's documentation and community meant the ongoing experience was better. These factors, messaging, onboarding, user experience, these are sales and marketing factors. Django won because of better sales and marketing. I'm not saying we had better banner ads.

Speaker 2: It won, for want of a better word, because it was better at getting the message out. I've also had this from the other side. Eight years ago I started a project called Django Evolution. It was a migration framework for Django. And at the very first DjangoCon, uh nine years ago Um I or sorry, eight years ago, I participated in a panel discussion with Simon Willison and uh Andrew Godwin, who are the three maintainers of the three migration frameworks at the time. And I think at the time The other two actually weren't publicly available. They were they'd were like released as a result of being on the panel.

Speaker 3: South was available.

Speaker 2: South was available, okay, right. And of course, as we all know, Django Evolution was eventually merged into Django Core as part of the 1. 7 release. No, wait, hang on. Oh wait, that was South. Yeah, okay. So I was first to market. What happened? I got tagged very early on with the label that evolution was magic. And I never managed to shape that. I never managed to reshape that narrative. I completely failed at sales and marketing, and the rest is history. So don't just write off sales and marketing. Don't get me wrong, many salespeople and their tactics make my skin crawl. But that doesn't mean that sales and marketing isn't important. It's just the opposite. It's incredibly important. But it does mean it needs to be done well. And marketing that works well for you may not be the marketing that works for your target audience.

Speaker 2: And it's not just about open source either. The same is true for any commercial endeavor. Buy me a whiskey and ask me how I know. Okay, so what works and what doesn't. What I'm gonna do now is what is scientifically termed a wild ass guess. Or to use the proper Django nomenclature, a wild ass kids. I don't have any hard data to back this up. This is entirely anek data. I have no reason to believe that I'm right. I've been involved with successful projects. That doesn't mean the projects that I'm involved in are successful because of these things. I just think these are probably the causes. And there are almost certainly factors that I've missed. Okay, so why was Django successful? Well it was in the right place at the right time. We were in a world where we'd be living with great big Java web frameworks, and Django came in and was able to show you how you could build a

Speaker 2: blog in 10 minutes. It was a a breath of fresh air with a new dynamic language and the uh the existing set of tools and whatnot that were available were very, very heavyweight. It had extremely good documentation from day one. Day one you landed on the project page and there was pages and pages and a fantastic tutorial that walked your way through my first experience of contributing to Django. was basically coming in, finding the project, and discovering that it couldn't do one little odd thing and then because the documentation was so good about explaining what it should have done, combined with the fact that Python is a really easy language to sort of read what was going on, contributing a major patch, and basically within a month I was a member of the core team. Now okay, this is like 11 years ago, so there was a lot more momentum. But the fact that that was able to happen, the fact that that that path, that onboarding path, was so easy, is part of the reason why Python was success or Django was successful.

Speaker 2: It also got set up very, very early as a very nice community. I don't know this was an explicit decision, but Jacob and Adrian were very, very aggressive about clamping down on anybody who was rude on mailing lists. And as a result, the mailing list, generally speaking, stayed very, very polite. Which made it a very welcoming community and a great place to hang around. Jang Revolution, the exact opposite. It was in the right place, it was in the right time, but it badly communicated the message. Cricket is another project I've been involved with. It's a graphical test runner. It was a very controversial idea and so I didn't really manage to convince people of the idea. It had some odd graphical choices. It was using tickle TK. And then I didn't follow up because when I found out the limitations of tickle TK or that I was sort of hitting against, I kind of haven't gone back and really refreshed that project. Beware, on the other hand, is one that I'm particularly proud of.

Speaker 2: I founded the project, and so it's really kind of been the focus of all the things that I've observed over the years. So, in my opinion, it's a combination of everything that I currently see to be how you are successful as an open source project. First off, it's an umbrella project. Beware is one name wrapping around a whole lot of smaller projects. That means I'm not trying to build a brand around each one of my little libraries. I'm building one big brand, BeWare, and then directing people and following people to all the individual parts. That has the additional benefit that it's a lot easier to understand the whole picture because you can understand what this does and what this does and what this does, and then you can see the path of how they're all connected, rather than trying to understand the entire blob at once. I've been very, very careful to be aggressively nice. This is something that I've kind of learnt from the OLAS in Django Girls.

Speaker 2: They are in their public emails, public communications absurdly friendly and nice and gregarious and bubbly. And initially that felt a little odd, but when you do that, it actually one makes yourself feel really kind of Because you're not focusing on the negative, you're focusing on the positive all the time. And people like to feel positive. Who would have thought? I've been very aggressive about outreach. Going aggressively after new maintainers and saying You want to contribute to Beware? I'm there. I will help you become a Beware contributor. I will be your mentor. I will help you get over that line. I will help you get your commit your commit bit. So focusing on that onboarding process. What does it look like to become a new user? What does it look like to become a new contributor? And rewarding those contributors with things like challenge coins. And every time that something does happen that is a notable event, new person joins the project, a new person does something that's complex.

Speaker 2: Tweeting about it, making a bit of noise on social media, and acknowledging all contributions, not just code. Things that are done socially, people who have written documentation, people who have contributed to the broader ecosystem, people who have contributed to other projects that have helped beware. I've been very vocal on social media, getting out there regularly, maintaining a cadence of saying things about your project, getting people saying, hey, look, this thing's out there, this thing's being this thing this project exists. Just knowing that it exists is part of the whole exercise with sales and marketing, because you've got to be in the front of people's minds all the time. I've also had a very balanced attitude to say to accepting patches. Um in the days of Django, uh particularly my own early days of Django, uh, if a patch wasn't perfect, I wouldn't merge it. And I'd probably go and say, take that patch and I'll I'll I'll fix it for you.

Speaker 2: In Beware, I've kind of relaxed that a bit. I've I've fallen back onto the world where the test suite tells you whether it works. You look at the code. Is the code better for being in rather than out? Does one more test pass? Does one more edge condition go? You can always clean up the architectural stuff later. And that means that you get more people in and you don't get people tied up in really, really convoluted uh you know uh project acceptance procedures. And tied to that, we're also automating a lot of these project acceptance procedures, automating continuous integration tech Automating linting checks. I've also been very careful to set community expectations around community culture that money is a part of this story. We are not expecting this to be everybody volunteered. We want money to be volunteered be part of this. We want a healthy lifestyle, a healthy mental attitude to the project, to be part of the project.

Speaker 2: So that later on down the line when we do get to the point where maybe there are commercial organizations involved. We're not tied to this internal schism of, oh no, it must be free, oh no it must be paid. Setting right now, it's going to be paid because that's the way we make things sustainable. All of this really comes down to the old quote from Pascal. Fortune favours the prepared mind. If you want your project to be successful, you need to plan for that success. It takes years to become an overnight success. I've benefited from being part of a large and successful project like Django. I'm on the very early stages of what I hope will be a similar journey with BWE. The things I've spoken about today, both in this talk and the one I gave this morning, represent the sum total of the knowledge I have about being successful. You'll notice though how little of it has to do with the technical aspects of the code.

Speaker 2: Open source projects are, ultimately, about communities. Communities of people with aligned interests acting collectively. This means that issues of communication, collaboration, social justice, inclusivity, these are intertwined with technical aspects because without the soft aspects, the hard aspects can't be done. This is something that's taken us collectively as an engineering group a long time to learn. And it's taken something where it's something that's where it's taken a long time to establish best practice. And we've still got plenty to learn. The key is to pay attention to it. Keep your eye ears open and your mouth shut and looks a ways to improve the social aspects around your project and improve your communication Thank you very much.

Speaker 4: We have the room for three more minutes, so you can either ask the world's shortest question or you can take your questions outside afterward.

Speaker 2: I'll also say the challenge coins, uh anybody I'm here till the end of the week to sprint, so if anybody does want to become a cool contributor, I can guarantee you will have one of these by the end of a two-day sprint. Probably even a lot sooner than that, we gave out 48 of them at PyCon US. So yeah, I'm also actively looking for benefactors and sponsors to help me continue beware. So if you or your company might be interested in pitching in or hiring me, come talk to me. Yeah. I'm also going to be doing Tintan Slams up in the mezzanine in a bit. What do you challenge? Come and ask me and I'll tell you. What's a challenge coin? Yeah, sorry. The challenge coin is one of these. It's a coin that you get if you complete a challenge. If you go to bwear. org,

Speaker 2: sorry, pyb. org, uh, there is a list under the contribution section that says challenge coins and uh gives you the full story.

Speaker 4: Awesome, thank you so much.