 At GitLab, the Handbook is an essential tool for our team and many of our community members. It's the foundation of our culture and helps us to live our values. Does your community have a Handbook? Maybe it should. Using Chaos and GitLab as examples, this next talk will show why Handbooks create communities that are diverse and inclusive. They level up the playing field for all community members and ensure the communities can be held accountable. Jaskarot and Naritzy also share the work they're doing with IEEE SA Open to bring Handbook standards to more open source communities. If your community doesn't have a Handbook yet, it might soon. Enjoy. Hi, everyone. We welcome you all to our session of Community Handbook, Best Practices for Diversity and Inclusion. My name is Jaskarot Singh, and I'm working as an open source research strategist and tech writer under Chaos, which is a project of the UNIX Foundation. So I basically help organizations, youth release and contribute to free and open source software, which is beneficial for both, that is for the community as well as for the end users. And today I'm leading the session with my co-facilitator. Thank you. Yeah, my name is Naritzy Sanchez, my pronouns are she, her, and I'm the senior open source program manager at GitLab. That means that I run the open source program. And I've also volunteered at many open source communities. I am a former president of the GNOME Foundation, I've helped organize conferences, and I'm currently part of the Chaos, a Chaos Working Group, and also IEEE SA Open. So let's take a brief overview about what we would be covering in this session. So before we go ahead, I just want to let you know that first up of the session would be covered by me and the second half would be covered by Naritzy. We have divided this section, like this, especially this session in three parts. So the first one is gonna be the community handbook and why is it important? Then we would be talking about the general components of the community handbook, the last, but not the least, like how you can basically join this movement specifically. So yeah, let's get started. Like what's the community handbook? So talking about the community handbooks, it has various attributes, starting with the documenting the process. So inside the community handbook, the community needs to define the processes involved within the community, like how the newcomers and existing community members can avail the leaderships involved inside the community. You just have to make sure that a technical documentation is different from the product documentation. So this is the kind of the community handbook documentation you could be writing, it's gonna be different from the actual technical documentation. Then we have the one centralizing the information. So again, we want to make sure that we have a single source of truth, like basically for finding like how to do things inside the community. You don't have to replicate up the things at different places and it should be easy for any newcomer to find the information at one place. Not really the last one, but the third one, which is very important. So basically it's about like how the newcomers can join the community. So you need to define the guidelines like how one can contribute towards development, design, documentation, and the outreach. So basically you have to lay down the processes that one can follow while participating inside the community. And again, you have to understand the accessibility and make this community handbook more easily searchable, keeping diversity in the mind as well. So you need to provide a better user experience to you. Well, it also enables the diversity. It can be accessible to various people who are actually present across various time zones like who works asynchronously. They can have the basic translator study up or like it is easy to translate so that people can understand it wisely. It also enables accessibility, keeping in the mind that the content inside the community handbook is really easily accessible by disabled people. And the last one, which is very much important that you have to understand inclusive language. So basically it enables by creating an environment that basically attracts the diverse contributors. So you also have to make sure that you don't use any such expressions or the words which actually are considered excluding the general group of people. Next slide please. Well, it also creates the transparency and openness inside the community. Like this is the way you actually get a chance to empower the contributor base, follow the best practices, like writing up a documentation for the community. You also have to make sure it is easily applicable by the other communities, either by the crediting to the setting the source. So yeah, this is how it enables the transparency and openness as well. Next slide please. Again, we would be talking about the examples of the community handbook where I would be covering the handbook or the chaos project and the GitLab handbook would be covered by the new agency. So yeah, let's get started. So chaos was established two years, I'm like probably like in 2017 at open source North America. So two years after the chaos establishment, the community handbook came into picture. There were a lot of discussions around it, but there was not a strong base to start this up. So in 2019, actually, this the community handbook was proposed as a project within the major Google open source program, which is the Google Season of Dogs, which is the program run by the Google where technical writers work with the open source organizations, helping them writing a better documentation. So I was lucky enough to avail this opportunity where I work with the chaos project, helping them build up the chaos community handbook. So there were again, a lot of many discussions around it regarding the tool stack we used and how to deploy it, but we finally ended up having the kitbook. I mean, like you are free to explore the chaos community handbook as well, but here we are just giving a brief idea about like how we have actually organized how it's actually started up. So the chaos handbook has been divided into four different sections, like which is about community contributing and mentorship. About section generally contains the general, the history or the rules and responsibility inside the community. And the community part actually contains the various subsection, which talks about the governance, the leadership ways, things, and the ways or the processes one can involve inside the community. Again, within the contributing section, it have various subsection, which includes how the newcomers can join this pace by contributing towards design, documentation, development and outreach. And since chaos has been participating in various mentorship programs, so the mentorship section basically contains about these development programs details. So next slide, please. Okay, so here you see a brief snapshot taken from the chaos handbook. This is the chaos history page. At the left side, if you see, it is the NABAR, which contains different sections and subsection. The center aligning is the information or the content actually needed for this specific page. Here, if you could see, I have defined illustration image, which basically talks about the chaos history, like how the chaos originated and how it is going now. It is always encouraged or suggested to have illustration image for the specific page for the people who are not really interested to get through the whole page, right? So this is, if you could see, like this is how I have drafted the illustration image over here. And the right side contains about the general idea, like how you can contribute towards it and the table of content as well of the specific page. Next slide, please. Again, this is another page taken from the handbook. So this is the partnership page, which talks about the different leadership involved inside the chaos community. Next slide, please. So I feel like this was all about the chaos handbook. You are free to explore it by redirecting to a specific link. Now let's hear about the Kitlab handbook from you. We'll see. Awesome, thank you so much. So before I begin, I just want to mention that unlike Jessica's handbook that you just talked about, the chaos handbook, the GitLab handbook is a company handbook, but because GitLab is an open core company, we also work on a daily basis with our community. So it sort of serves the purpose of both things. And it creates a whole new level of transparency. So I'll give a brief overview of what that is. First of all, when each new team member on boards, they're expected to read through the handbook and contribute. There's actually something specifically in our onboarding that says that if you notice content that isn't clear, that maybe you have questions about, then it's likely that other people have questions about it too, so you should go ahead and update it. We use GitLab pages to host this as the tool that we use for the community handbook or for this handbook. And that means that it requires editing through merge requests or MRs. While that might seem a little bit scary to people who are not familiar with how merger requests work, it actually is a great thing, because GitLab allows you to create merger requests in a way where it's almost like editing a document, and then it also gets people familiar with the way that merger requests work so that they can start contributing in other ways. So in that way, the community handbook ends up being almost like a gateway to other types of contributions, perhaps updates to a website or things like that. In each page, there is a little image on the top right that shows which people or who is responsible as the code owner for each page. These are basically like maintainers of projects or yeah, something like of a code base. So essentially everybody can update the content, but the code owners are the ones who are responsible for making sure that the content is continuously updated, and also they can make the final decisions on whether to include something or not, or how to format it, things like that. There is, here, this is like the very beginning of the handbook, so you can see that there is an introduction to the company about the mission, the values, what kind of communication, what tools we use for communication, et cetera, and each team is expected to manage this. They have their own section, and then besides that, as I mentioned, each person is a code owner of a particular page to kind of show also who is responsible for that area or who can take leadership. So the last thing that I wanted to highlight here before I move on is that this is distinct from GitLab docs. So as Jessica mentioned before, the community handbook should be something that is different than the documentation, so or than docs. So communities have already sort of recognized the importance of technical documentation, and now it's time to start documenting processes in this new community handbook like mindset, all right? So I'd like to show another page here of what our community handbook, or what our handbook looks like. Excuse me, I'm struggling with allergies, so my nose is a little stuffy. On this page, you can see that I have all sorts of information about, for example, what my quarterly goals are or what metrics I use for the open source program. So this page is distinct from our website because it really talks about the processes, and so hopefully this gives you a little bit more of a visual of what I mean by this. There are really detailed things like what products use the open source program uses when it gives away free licenses or things like that, so it's very detailed. And then in order to maintain the content fresh and make sure that it's constantly updated, GitLab has adopted a handbook-first culture, and what that means is that we should always respond with a link. And this gets people in the habit of making sure that what they're trying to say is documented in the handbook, that it's updated, that it's still relevant, and then it also helps the people receiving the link to be able to go and look through it and make sure that it's easy to understand, or if not, they should contribute back and help make it easier to understand. So by adopting that handbook-first culture, it's actually key to the success of actually rolling this out and maintaining it. So it's something that I think that every community should adopt if they're trying to include community handbook for their own community. All right, so hopefully we've now given you a background on what a community handbook is and why it's important. So now we're going to talk about how you actually begin a community handbook. And I wanted to start off by just saying that this is all sort of in flux, the term community handbook and also the different components, all of that are still being defined. So we have joined, Jessica and I have joined the IEEE SA Open Community to help define those standards. We encourage you to join us and I'll have some information about that at the end. But again, I just wanted to start off by saying that this is a work in progress. So what I'm sharing with you today is just the beginning. Okay, so when you're first starting to roll out or develop a community handbook for your community, you first need to make sure that you create buy-in. In order to do this, you need to start off by documenting your proposal. This can be in an issue on a wiki or whatever tool that your community uses. It should be something that you can link to and again, have a larger conversation about. So that's why having it in an issue or maybe in a wiki and then starting an issue so that people can have a conversation about it is really important. You should then request input from the community because if you just make a decision and then try to roll it out, it's likely that it won't be adopted. People will feel like it's being forced on them or that it's incomplete, et cetera. So having a timeframe for requesting input, maybe it's a few weeks or even a few months really helps people feel a shared sense of responsibility and they feel included in making something. This is incredibly important when you're having really big changes to communities or in processes or just the way that things are done. After you have that period of community input, it's then time to get formal approval from the governing body. So this could be a technical or community advisory group or the board of directors, depending on how your organization is set up and having this formal approval, just having the governing body say, yes, this is important to us and we want to establish a working group will again, will lend it legitimacy. Once that's done, you want to set up the working group. So this can be just a group of interested people. Again, you should let anybody express interest and join the working group, have a core group of people that are doing it or you might want to tap into something like the Google season of ducks program that Jessica mentioned earlier and have somebody lead it and then that way it's somebody who is taking it on as a project. Something that's really important whether you go with a working group or have somebody lead it through again, the season of ducks type program is that there should be regular updates to the community about the progress and to gather input. So maybe once you've decided what topics you want to have at the top level, you send a message to the community or an update in the issue when you say, this is what I've worked on this week. If you have input, feel free to let me know. And so in that way again, you're creating multiple chances for the community to weigh in and help collectively shape it while still having that momentum moving it forward towards actually completing it. And lastly, when you have finished creating the community handbook or this first iteration, it's time to employ change management skills to roll it out to the community. And for those of you not familiar with that term, change management, it is essentially a skill set that you can develop to help really roll out big changes to any organization. And so what this might look like is for example, gathering people that have high visibility in the community. These might be maintainers of projects or strong community advocates and getting them to understand what the community handbook is, how it works, how to update it, et cetera. And then they are more likely to help newcomers or do it and to be able to themselves adopt that handbook first culture and then start to spread it to the rest of the community. So change management is still a skill that I'm developing as well, continuing to develop. And I encourage you to look into that as well. The next thing when starting your own community handbook is thinking about the tool stack or maybe not the next thing, but a very important part is deciding what tool you're going to be using. And so we think that there are some desirable characteristics. This might not be a fully inclusive list, but we think that it should be searchable, accessible, visual, user-friendly. And we think that there should be some form of version control. So keeping these characteristics in mind, we have recommendations for you to look into. That's GitLab Pages, GitBook and GitHub Pages. And there are lots of other documentation tools, there's Wikis and a whole bunch of others. But these are the three that we recommend looking into first. When creating your handbook, you also need to think about the topics that you want to cover. These are some like high level topics that you might want to consider. The first is having an about section that talks about the community's mission, the vision, the values, history, the governance model, code of conduct, et cetera. So this helps to give newcomers an idea of what the community stands for and the various ways or the things that they need to know like the code of conduct. Then there should be a section about the different teams or the groups within the community, how to onboard onto each team and any specific processes that the teams or groups follow. There should also be a topic about the handbook. So this is kind of like a meta category of how to use the handbook, how to update it, et cetera. And then we think that there should be some sort of social component. So how to meet other community members or tools that you use to communicate. All right, you should also, when creating any kind of documentation and again for this community handbook, you should be keeping in mind using inclusive language. And like Jessica mentioned before, this is really important. So try to avoid using acronyms or referring to people just as he or him, making sure that you really take into account just something that will be friendly to everybody and also that anybody from around the world will be able to jump in and use. So don't use elaborate language. And then accessibility is really important when you're creating your handbook and then you should have a tone, a documented tone and voice so that there's a level of consistency throughout the community handbook. Another thing that you should be thinking about as you start your handbook is how updates are handled. And we mentioned these before so I won't go into them too much, but having code owners or maintainers for pages or sections and then having that handbook first mindset or culture is really important because the worst thing that can happen is for you to put in all this effort into creating the handbook and then for the content to go stale and for it not to be used. So making sure that updates are something that are routinely done is incredibly important. All right, so now I'm going to tell you how you can get involved in the community handbook movement. And before I start, I just want to bring attention to this QR code that we have on the right hand side. If you scan it, you'll be able to see the PDF version of this presentation with links to various resources. There are links throughout the presentation as well but we have a section specifically on resources and we hope to be adding to this library. So go ahead and scan that. And so what if you would like to join us? The first thing is to help us define the standards. You can join the documentation and curation team at IEEE essay open. And this is where we meet on a bi-weekly basis to define those standards. We also want you to help us coin the term. And that means help us make the term community handbook well known. It's fairly new, so we want people to know exactly what we mean when we talk about what a community handbook is. And then spread the word in your own communities. Feel free to copy this slide deck and use it to help pitch the idea further. And again, we're going to try to continue to create more outreach materials. So keep checking back on our resources library. And then we will welcome outreach ideas from you as well. Feel free to reach out to us on Twitter or LinkedIn. Jessica and I both would love to connect with you. With that, we thank you very much for attending our session. Thank you and we'll see you around GitLab commit. Thank you, bye-bye.