Zainab Daodu – Narrative Infrastructure: Storytelling to Grow Open Source #FOSSBack

This talk discusses the importance of storytelling in developing and nurturing open source communities. The speaker, Zainab Daodu, emphasizes how effective narrative infrastructure can help new contributors understand a project's purpose, priorities, and contributions. Drawing from her experience as a senior technical writer and founder of Write Tech Hub, she outlines how projects can enhance their documentation beyond code to become more inviting for contributors. Zainab illustrates the significance of clear content, such as README files and contributing guidelines, to provide context and assist contributors in their journey. She shares best practices in maintaining narrative, including onboarding routines and regular updates, to keep contributors engaged and informed. By fostering a clear project narrative, maintainers can reduce burnout and enhance collaboration, ultimately growing their open source communities.

So, hi again, everyone. Thank you for joining my session today. Um, I'm super excited to be able to speak even though I'm not able to join physically, um, but I'll try to make it as, um, engaging as possible. So, um, today we're going to be talking about how narrative, um, how you can use storytelling, um, to grow open source communities. So, beyond um, your code, beyond, um,

whatever you have in your project, like how you can tell the story of the project to help contributors come on board and also still, um, stay connected to the project. So, my name is Zainab Daodu. I'm a senior technical writer. I started out my career as a software developer writing code, before I somehow discovered like the importance of documentation in, um, products and software products as a

whole. Um, and then I started working on documentation, and since then I've contributed to open source projects like Jenkins, Wikimedia, and work for organizations like Google, Cisco, Tilio, and others as a technical writer. Um, also I founded Write Tech Hub. Write Tech Hub is a, um, technical writing organization and community that on one hand end has a community that helps technical writers upskill, give them all the

necessary, um, skills and resources to be able to upskill as technical writer and get them ready for the job market. And then we also provide technical writing services to organization, open source projects, you know, that need our services. Some of the projects that we've worked with at Write Tech Hub open source project, um, is Mautic, and then we have others, um, we've contributed to through our community

initiative. And from these experiences what I'm going to be um giving this talk today on how you can use storytelling to grow your open source communities. let's get right into it. So, before we get started, I I want to all of us to think about open source projects that we've all contributed to. And some of these projects have like solid code, they have tests, they have clear

structure, everything look looks good on paper, but yet um this open source community still struggle to attract contributors. And you find out that maintainers end up doing most of the work, which then in turn leads to burnout. And most times the problem is not code, and it's not people, it's just context. Even I myself as a contributor have struggled with it. You get into an open source

project, you're excited about an open source project, you want to contribute, but then when you get in, you don't understand the project well enough to start to know where to start or how your contributions can effectively help um the project. Especially when you talk about someone like a technical writer and all that, you don't want to just be fixing typos. You want to make substantial contributions to

the project that um you know, where you know that those contributions have like major impact to the open source project. And the thread that connects the code, the community is what I'm going to be calling um narrative infrastructure. So, you can see this simple illustration on the screen now. In example A, the project has very little activity over time, maybe just one person or few people are

pushing changes. But then, in example B, we have multiple contributions happen more regularly and involve more more people. Both of these projects have good code. The difference is often whether contributors understand the projects well enough to participate. And that understanding usually comes from the story the project tells about itself and how it makes it visible and accessible to the contributors, to people who want to contribute to

the community. um when I talk about narrative infrastructure, I'm talking about the storytelling for your project um that helps everyone, including newcomers, maintainers, and even the future you, understand what the project is, why it exists, and how to contribute meaningfully to the project. So, this is talking about um context that answers questions like, "What are we building? Why does it matter? Who are we building it for?

What counts as a good contribution? And what's considered important or not? What is a priority? What is the project roadmap?" You know, so when a project has this all these questions answered clearly and told through documentation and community practices, then contributors can clearly see and easily see where they fit without having to rely on maintainers or always feel the need to ask questions in the community to

understand what they need to do and how they can how their work impacts the project or what actions matter most. So, let's say um let's let's paint it a scenario. Let's say Alex, a developer, comes to an open source project and is excited to contribute. She understands the language. She's eager to help, you know, sees a list of open issues, pick one that looks simple and gets

to work. But then, hours into contributing, um Alex hits a wall. She has no idea, you know, whether the issue is actually a priority, you know, because there's no traction, um and then what the intended outcome should be because sometimes you open PRs or you're asking questions, and it feels like, "Oh, I'm working on this. I'm working on that. I'm working I'll get to this when I

finish working." Maintainers are like, "Oh, I will get to your issue." So, it now begins to look like, "Is this thing I'm working on even a priority? How can I know what is a priority right now in the project so that I can contribute to that and get more traction and more impact in the work and not just sideline." So, um she doesn't know if the work

is um actually helpful. And then, frustrated, you stop contributing and moves on because nobody is really attending to your It feels like whatever you're working on is not a priority. So, this is exactly where the problem um of narrative infrastructure um what narrative infrastructure solves. if a project handles this well, before Alex even contributes to the project, she should be able to tell what is a priority,

what is important right now, um how to get started, and answer a lot of questions before even having to ask anybody questions. And this matters because it makes the purpose of the project visible. We've talked about it. And um it helps new contributors understand how to begin contributing. And then, without narrative, everyone else is slowed down. So, how does it grow open source communities? We're going to

get to into like how to create this, but I want us to understand like the importance of this um before we get into like the how we're going to do this. um it's more or less like a chain reaction. When your project has like a clear story and context, um we've talked about it gives contributors clarity. And then when contributors are clear on what they need to

do, they have the confidence. Um and then that confidence empowers them to jump in, contribute, and even want to support other people. And then once um that confidence is there, it leads to contributions from them. They're able to submit pull requests, you know, suggest improvements to the project, even things that goes beyond the issues that maintainers have opened because they understand they understand the project, they know

what the project is trying to achieve, they can see the vision of the project, and they can make meaningful contributions beyond just pull requests, you know, and issues. And then um they can share ideas because they know their efforts are meaningful. And when contributions are smooth and intentional, the contributors are more likely to stick around. They don't just um submit one pull request and go. They keep

contributing and contributing because they see the vision of the project. And then as retention grows, the community expands naturally. You have more contributions contributors, you have more contributions, more maintainers, more collaboration, and the project becomes self-sustaining. So, let's now go into what how the backbone of narrative infrastructure, how you can create good storytelling for your project. So, on the screen right now is a readme file. when

anybody comes to So, before we even go into the readme, the backbone of creating narrative infrastructure or good storytelling in your open source project is your content. Before we even start like what kind of content. This is actually what tells people the story. Um, how you structure the content, your readme files and all the different files you're having in your project. So, the first thing everyone anyone

sees when they come to your project is your readme. And a strong readme tells the story of the project, what it is, what it solve, who it's for. And it also gives um, contributors a sense of how to get started and where they can make meaningful impact. So, on the screen now we have a readme file for um, data sync. It's okay, but in all honesty, this

readme feels flat. Um, you get a sense of what the project is about, but the priorities, ways to contribute, and all that is not really clear um, from this readme file. And when you come here as a contributor, you have some information, but when you want to go further into contributing, understanding like, you know, the vision of the project and just, you know, key things to help

you understand like, is this sustainable for me? Do I really want to you know, do I want is this something I want to keep contributing in? You don't get that all that context from this readme. But then, when we look at this readme, um, it gives you context. You understand the story, you understand the priorities, you understand where to start. You have support, you have things like

community meetings, you know, that tells you how to get involved in the project, listening to you know, adopters, so many things in here that helps you, you know, understand this project and the importance of this project. So, this is the first step to turning a visitor into a confident contributor. And you want to ensure that you have all the information that you need to help your project

and your community grow. So, and then another important file after the readme is the contributing.md If your readme is your front door, then think about your contributing.md as like a butler that welcomes people inside and tells them, you know, what to do, you know, how things work here. So, let's look at Data Sinks again. The contributing.md file again is okay, but it's vague. It leaves a few

steps like fork the repository and run test. How do I run test? You know, and it doesn't explain expectations like guidelines for contributing, you know, maybe um process for opening a PR, expectations, which is another important thing to set when, you know, explaining um how people can contribute to a project because a lot of times when people see these get the PR and all that, they're waiting

because the expectations are not set clearly. Who is Who are the reviewers? Who to add to your PR and things like that. So, contributors would have to make a lot of assumptions with this kind of contributing.md file. But then, um this is another contributing.md file from Kubernetes. So, it clearly lays out the workflow. It uses labels, you know, to guide people to the right tasks. Um it

shows examples of what good contributions look like. It explains what to do, why it matters, um you know, code of conduct. Uh it has the contributing guide that has like prerequisites, you know, what you need to have before you can So, with all this information here, contributors can, you know, step in confidently because they understand how the project works. And it doesn't stop with readme and uh

contributing.md file because I've worked with a lot of open source projects that once they have these two file, that's it. your open source project, you know, goes beyond that. You can build your narrative infrastructure by using things like issue templates. It makes it easier and keeps things con- consistent. Makes it I mean, reduces the guessing work for contributors. How do I create an issue? What should be

in the issue and things like that. When you have an issue template, it answers all the questions. Then you have pull request template also. When you're creating a pull request, this is what you should have in the pull request. This is um who you should tag for review. This is how you run test or these are the tests that would run in your pull request and things

like that. Just helping them understand this and less guesswork. Frequently asked questions. When people and these questions coming frequently, you put them somewhere where other people can get the answers. So, you don't have to keep repeating the same thing. Change logs, very important. What is changing in the project? What is new? So, that at every point in time people can, you know, stay in sync with the

project. And then style guide, very, very important. Um whether it's even for any kind of contribution to be honest at this point because it's not just documentation. Even um your code, you have guidelines and things like that for writing code. Um same thing if you're working on things like designs, you have um design guidelines, documentation guidelines. You want to have all these guidelines accessible to people um

so that it's easy. Some people would, you know, assume and just jump into the project, contribute, and decide, "Oh, I really want to do this. But then, when there's no guideline, they start getting feedback upon feedback and they're like oh, they get exhausted at the end of the day and they're like do I really want to go for another round of all this feedback? Um while some

will be like oh, I don't even know how to do it this I will not get started. But then, when you have a style guide and then you make it accessible, um then, before anybody even submits contributions, they know exactly what the expectation is for the project and they can submit like contributions that will feel impactful. So, um this is another um good guideline that shows like

guidelines for opening a pull request, you know, um some issues that people experience when opening a pull request, um like not having a signed CLA CLA and things like that. Um and so many guidelines in here. So, this content content like this will help contributors understand what expected and how to move through the um workflow. And then this is another section that explains best um best practices.

All this um documentation or all this um storytelling I've been screenshotting is all from Kubernetes. So, um this guides people on things like writing clear commit messages, linking issues properly, giving reviewers enough context to understand the change and all the guidelines that is needed to contribute to your project. Um a lot of open source projects today assumes that people would know the right way to do things,

but remember as open source communities, we're trying to attract different levels of contributors. So, you want to you don't even have to have all this information in your project. You can link to external sources that explains oh, how do you create write a good commit, you know, what's the best practices for opening a pull request and all that to make people more confident in contributing to your

project and they can always reference it as time goes on. Even if they take a break and come back and want to contribute, they have these guidelines to remind them of the standards of the project. They don't have to come and repeat those questions, which make people feel uncomfortable when they want to contribute. And we know even maintainers get overwhelmed by answering the same questions over and

over again. So, now we've talked about narrative infrastructure as the content, the next layer is practices. Routines and processes that helps to keep the story alive. So, it's not enough to just have your content content and leave it there. You also need to have practices and processes that would help to keep the story alive and not make it forgotten. So, for instance, onboarding routines um onboarding routines,

you know, help new contributors get oriented quickly and start contributing meaningfully. Sorry, that's my source. Okay. Um so, and then you have regular check-ins or team You have regular check-ins or team updates, you know, to uh make sure everyone knows what is happening, what decisions have been made because even when you have the vision for your Go and meet grandma. I'm coming. So, even as you have

like um the vision of your project, the project is a living thing. It's growing. You're making decision as time goes on. Um you the road map is changing. New features are coming. You know, the ecosystem is really moving fast. You want to keep in So, you need um regular check-ins. You need team updates um to make keep everyone up to um speed on what is going on

in the project. Even if people are not able to join, record the session, have somewhere in your project where you keep these recordings. So, anybody that wants to reference it later on, you know, can see like what is going on and be involved in what is going on in the projects. One um thing that I've seen a lot of people struggle on with um struggle with open

source project, especially since it's something that you don't do full-time, is keeping um staying up to date on what's going on in the project. Um how do I know what is changing? How will I How How do I know what decisions are being made? So, having these um regular updates um is very helpful and not just for maintainers, but also something that you can um involve contributors

optionally to also participate in to understand what is going on in the project. Um so, we've talked about contributor onboarding session, maintainer syncs just for maintainers, issue labeling, you know, labeling issues properly, change logs, style guides. All these are things um practices that also help um keep your um story alive. So, everything we've talked about comes down to this. Narrative is how people understand your project. Um

so, when you invest in this um by having clear content, thoughtful processes, you're inviting people to become collaborators. And this is what transforms a collection of code or what your code base, your task into like a growing community. And it is what helps you scale your project also. Because at the beginning, it's okay to answer a few questions from a few people. But as your open source

um project grows, you no longer have the bandwidth to answer everybody's questions individually, and you want to make sure that everybody um understands your project um the way it should be. So, this is what helps you scale and maintain momentum without burning out a few um maintainers in the process. Okay. I just want to make sure. So, how can you get started building your narrative infrastructure? So,

first, start by being able to tell your project's story. Who is it for? Um what problem does it solve? What are the main goals? Um this is the foundation if contributors Um this is the foundation. Once contributors understand the story, everything else makes sense. So, once the story is clear, next, turn that story into content and um practices and processes through your readme file, your contributing file,

your issue templates, PR templates, all the resources that contributors are going to be using to interact with that project, you want to put your story into that content. And then finally, sync with the community to make sure that everybody is on the same page. Ensure that everybody um is able to access the story, the content you've created, the practices, everybody is aligned. and then you're able to

um keep the community in sync. um if you already have like um if you have an open source project, um three um I'd like you to do these three things to make sure that your narrative infrastructure is in place. So now take a quick moment to audit your communities narrative like first, can a newcomer can a newcomer explain the project in one sentence? If not, your story

is not clear. Like when you ask newcomers, people who come on the project like what project is, what it's about, can they answer it clearly? And then next, do contributors share the same vision? If people have different ideas about the project, then contributions will definitely be inconsistent and can lose impact. And then finally, where does the story leave? If contributors have to dig through documents, have to

figure out the path themselves, you know, have to struggle to understand um it is, then it means that you need to work on practices and the structure of your infrastructure. And then if your answer to these questions that I asked previously is no, if you don't have story, then you need to write, you know, a a clear project narrative, include the aim, the goals of the project

so that contributors can have context. If there's no alignment, define the project values, um contribution principles, um PR templates, contribution guidelines, issue template. This aligns contributors and keep contributions to high quality. And then if there's no visibility, make the story easy to find. Is it structured properly? Are you cross-linking where you need to cross-link, you know, so that contribution um tools do not have to hunt for

context when contributing to your project. And then by doing these three things, you can fix common mistakes and barriers to building a healthy, growing open-source community. So, yeah. That's um Thank you for taking the time to listen to my talk today. I hope you can take some of these ideas um back to your project and start making your stories very visible and actionable um for community members.

So, if you have any questions, thoughts, or experiences, please I would love to hear them. Um let's let's discuss. Thank you. And we have our first question. Yeah, hello. Thank you for your talk. It's inspiring. Um So, um I'm thinking about difficulties to start with the content. Okay. I don't like of capacity or priority or or maybe even like of to simplify it talent or something to

write it. Um what is your view on uh uh generative tools? And are there risks to using them to kickstart this uh aside from the maintaining aspect? So, to kick off with the content. Okay. so, I think using generative tools is is good. It's a good idea. But, the thing about using generative tools is that it's best practice best practice to have something for those tools to

build off of. Because when you just ask the tool to write from scratch without any guidelines, without um any standards to go by, then um you just have to take whatever it it gives you out without understanding if this is even best. And a lot of times when you give these generative tools content or work do without prompting them properly, giving them proper guidelines to work with

and all that, you do not get high quality results at the end of the day. So, yes, it's okay to use generative um tools, but you need you still need a human in the loop. One, to ensure that you have guidelines to start with that these generative tools can use. You have standards in place, um you know, checklist in place, things that the tool can use as

a guideline. And even when it generates the content, this human in the loop would help you review the output to ensure that it is accurate. Because then again, we know that these tools hallucinate, you know, and sometimes they they make mistakes also. Like, when you give guidelines, they they can mix things up. So, you want someone to be there to review and make sure that whatever output

or result you are getting from these tools is um of high quality. So, that would be my advice. Thank you. Do we have another question? Uh thank you for your talk. Um so, I'm thinking about when when people in the process of maybe becoming a contributor, if they drop out, I as a maintainer apparently will never know. But, if they are on board, uh it would be

interesting what what actually kept them there. So, do you have any experiences with like reviewing and researching the people that actually made it into the project like in a structural way? so, yes, um I think one of the ways that we've been able to, without kind of like um people too much work to do, understanding is through community practices. So, um we found out that new contributors

are always like looking for how to engage, you know, and engage with maintainers and all that. So, when you have like community practices like the um process I talked about, maybe like an onboarding sync. It doesn't have to be something that happens like every week or every month, but maybe every once in maybe once in a quarter, people that join in that quarter, we have this, you

know, onboarding sync to talk to them, find out like what interested what interests them about the project, find out about what are the issues they've encountered. This is a good place to get answers from people without having to, you know, send surveys and all that, which most people don't feel at the end of the day. And then it helps these new contributors feel heard and feel seen

when you have things like that. And then also in Slack also or whatever community forums that you're using. This is a good place to also find out like questions that people are asking, issues that they are experiencing, and and all that. So, it would be helpful to have like maintainers who you know, really focused on the community side of things in terms of like, you know, contributors

joining the community, leaving the community, managing them, answering their questions and all that. That's why now you have people like community managers and all that. They would be able to help you put more structure in place into managing your contributors, seeing where they are dropping off, what the issues are, and helping you put processes in place to solve that. I hope that answered your question. Thank you.

Do we have more questions? A short one. Yeah, maybe not sure if this is a question. It's a bit of an observation. Something I missed a little bit in in your presentation and I miss in a lot of projects is more visual storytelling about the the project. You know, when you get to a project and there is a big read me and maybe okay, I can read

it. What if there was a little bit of visuals like diagrams and things like that, it would be helpful. Like have you seen like best practices for this and like what to do, what not to do? Yes. Yes, I agree that visual is a very is a very strong point. The reason why I didn't actually talk on visual is because um there's someone else that is speaking

on this similar topic to my narrative infrastructure, but she's going to be focused on visuals specifically. I think her session is sometime later today if I'm not mistaken. So, that's the reason we coordinated before the event. So, I spoke about I'll be speaking about content alone and she'll be focusing more on the visual side of things. So, she would talk more on that and if you're able

to attend then you'll be able to get answers to your question.