 Okay. Hello, everybody. This is Ray Pake. I'm a community manager at GitLab. I'm very excited to be here with my good friend Sophia from Ericsson Software Technology, and she'll introduce herself in a few minutes. Hopefully, everybody is healthy and safe. It's too bad we can't be in person in Austin, but it's still good for everyone to get together virtually and talk about open-source software over the next couple of days. The topic is something that's near and dear to both of our hearts, documentation and open-source projects. If you've been involved in a lot of projects like I have, and Sophia has, you'll find that documentation is a topic that's talked about very often, and people realize the importance of documentation. Unfortunately, in some of the cases that we've seen, it doesn't quite live up to the expectations that people have for documentation. I wanted to share our experiences and some of the things that we tried and learned over the past several years. I just wanted to remind people, if you have any questions during the talk, please feel free to type your questions in the Q&A box. Hopefully, we'll have plenty of time towards the end to answer the questions you have. Both Sophia and I will be monitoring those questions as they come in. Without further ado, let me turn things over to Sophia, and then Sophia will cover the first half of the presentation. Thank you so much, Ray. Hi everyone. I'm Sophia Valin, and I work as a project manager for Ericsson Software Technology. Over the past four years, I've been the technical lead for documentation for OpenFV and ONAP. I'm also one of the initiators for the cross-community working group for documentation within LFN. With that, we can get started. Why is documentation important? We all know that open source is not only for developers and not all people can read code, which makes it a really important entry point for users and other interested. It's key for onboarding and project introduction. It's just super important. If you don't have any docs, it won't be too easy to use whatever incredible stuff that you guys are developing. Documentation should basically always be considered as a natural part of the software delivery. What common challenges do we see then? It's often done by a few volunteers, and even if you volunteer, you might not have too much experience in writing technical documentation. It's more often started in the very last minute. It's treated separately from the code. We tend to see lack of consistency, poor quality, and then this vicious cycle just repeats itself. What can we do then? I will now give you some insights in what we have been doing for the LF networking. As you can see here, a couple of years ago, a cross-community working group was established for LFN with the goal of providing a common way of handling documentation. We saw the need here since a lot of the project was struggling with finding a sustainable way of working with documentation. Not all projects had a designated lead for the DOCS project, which led to a community effort with more often a low priority. We also saw a necessary overlap of maintaining guidelines and so on. What did we achieve? We did achieve way more consistency across the project within LFN. We provided clear and simple guidelines for how to work with documentation. Documentation contributions are treated in the same way as code contributions, and this goes for metrics as well as recognitions. The projects do keep local style guides and templates since this might differ a bit between the projects. As you can see here at the bottom of the slide, we do have a common documentation and tool guide for all the projects within LFN. Moving to some more concrete examples then. I'm going to use OWNAP, the Open Network Automation Platform as an example. I've been working closely with David McBride, who is the release manager for OWNAP, among other projects. We're trying to find a sustainable way and an easy way for projects to work with their documentation. First of all, we have designated milestones for the documentation for each release cycle. This goes all the way from planning to having your repo structure with associated templates, reviews all the way to sign off. We don't let projects get away with not completing their documentation, and I think that's a really important one to have the TSC and others really emphasizing the importance of documentation. We do have two hackathons per release cycle, which has also been very appreciated by the community. This is basically just a Zoom call running open throughout a full day, and people can call in if they have questions or need any support, or it could also just be used as a reminder that maybe you should set aside some time to work on your docs. We provide templates with expected level of content, this is currently a working progress, but I know that since I said earlier, not all people have too much experience with writing technical documentation, so to have some indications in templates has also been a great help. Of course, we're tracking all the documentation, work and tasks in JIRA as we do with the rest of the work, and then we do keep all the documentation stored in the respective project repo, and this is to basically enforce the responsibility and make sure that the project really takes the responsibility and feel that they own the documentation. With that, I'm going to give the floor back to Ray. Thank you, Sophia. Let me advance the slide. Just a bit of the context, I had experience, Sophia mentioned the OPNFV project, so I was able to see working with Sophia, there's been an evolution of how documentation, both in terms of process and structure-wise, they've sort of evolved over time, and I remember the first docs hackathon that we participated in a few years ago, so it's great to see the growth and maturity of docs in large open-source projects in Linux Foundation Networking. So I want to switch gears to, like I said, I joined GitLab about two years ago, leaving the LF Networking communities, and so obviously this is a transition, and Linux Foundation Networking has, I mean, dozens of member companies participating, member companies and organizations, and a lot of volunteer contributors that have been contributing to not only technical work, but also docs as well. GitLab, obviously, it's an open-source project. I mean, we have thousands of contributors from the wider community that have contributed to our product, including documentation, but it's definitely different from projects like LFN, where this is a single company-led project, we also have, you know, within our staff at GitLab, we have a full technical writing team that are professional technical writers, whereas in projects like LFN, other open-source projects, you know, mostly a lot of the work is done by volunteers. But, I mean, having said that, I mean, we definitely love having wider community members that are contributing, because, I mean, there's no places like docs where having, you know, extra pairs of eyes is very helpful, including, like, starting with things like, you know, simple typos or everything else. So we love getting contributions from wider community to help our documentation. On this first slide, you'll probably see some of the common themes that Sophia's already talked about, and this is something that I noticed pretty early on in my days at GitLab. Just like it is at the LFN or other projects, documentation is a core part of our product. It's not separate. I mean, if you want to find the docs for our various projects, you see some of the examples here, our flagship GitLab project, Omnibus, runner charts. If you want to find the docs, just go to the repo, and it's at a logical place where you think it would be under the docs directory. So go to, like, the GitLab project, and then the doc will be the same place where you find other things like code. So it's not at a separate repo or separate place somewhere. It's where the project lives. I mean, similar to having milestones at the LF networking projects for documentation for projects to go through the release cycle, we have this documentation page for definition of done. So when you contribute any improvements to our product, including docs, you do that through merge requests at GitLab. And if you go through the checklist, one of the items is if you're introducing a feature or if you're fixing a feature that's going to impact users, you need to have a documentation. And that standard applies equally to GitLab team members and wider community members. And if that requirement's not met, I mean, the merge request will not be merged, and then you'll not make it to our next monthly release cycle. Obviously, if the wider community members need help with documentation because they've never done it before, we're obviously happy to help them out, but that step can't be skipped. Like if you want your merge request to be done, it needs to have the documentation requirements met. So that's one of the things that we have in common with LF networking. So how do you contribute to documentation? Like I said, I mean, I published a blog post talking about achieving like a 3,000 contributors from the community. The way you contribute to docs is exactly the same as the way you contribute to the code base. You do that through everything starts with the merge request. That's sort of one of our models at GitLab. I have a link to a documentation there. So the process you go through to submit an MR for documentation is exactly the same as it is for code. So a lot of people, as Sophia mentioned earlier, a lot of people start getting engaged or contributing to open source projects through documentation. So once you mastered how you get through the review cycle or submitting an MR, getting a triage reviewed and merged, once you mastered that mechanics of how you make your contribution to documentation, the process is exactly the same as it is for the rest of our products like code. So we definitely have a consistent process. So you don't have a separate process you're dealing with for code versus documentations as an example. For docs, I mean, we do provide a shortcut. So if you look at any of our documentation pages at GitLab, go to docs.gitlab.com and go to any of the pages. If you scroll all the way to the bottom, you'll see that little publish area says help and feedback and you'll see a link for edit this page. So if you click on that link, it'll take you directly to that page and you can hit the edit button and start editing the page whether it's fixing a typo or adding your information that you think is missing. So you don't have to dig through the directories or folders to figure out where that particular file is located. So just hitting that link will directly take you to the page to make your... We really want to make it easy for people to contribute to docs or documentation. And we have the similar link for all of our websites as well. So if you go to about.gitlab.com and whether you're looking at partners page, community page, or pricing page, if you find something that you want to fix it's just a simple matter of clicking on one of those links and then you can start your contribution. So we have that extra shortcut there for documentation but the process itself, the rest of the way is pretty consistent. So that was really great to see when I first joined GitLab. So having the consistent processes I think is very helpful and important. Moving on to the next slide. And Sophia talked about this as well for recognition within Linux Foundation Networking. And as a community manager, I mean nothing makes me more happy than recognizing community members from all over the world. And for recognition I wanted to provide like one example. So on the left-hand side of that, the slide, that's a mug that you can order once you get your first MR merge. So there was a contributor there who celebrated receiving their mug on Twitter with the hashtag as well. And so for first MR that gets merged, whether it's code or documentation, as far as I'm concerned MR is an MR is an MR. So whether you contributed an important code bug fix or if you just fix a simple typo, it all counts the same. So we want to make sure that people that are contributing to documentation is recognized and awarded. So that's one example on awards. And then in terms of like community metrics, I think Sophia mentioned it as well. We have our contributor dashboard go to contributors.gitlab.com and all the MRs merged or contributor accounts there that counts all MRs including documentation improvements. So we don't have a separate metric for docs versus code. It's just all, they're just all in one place. And I apologize for the last image here, like the red highlighted box. I think I moved over one word converting the slide to PowerPoint meant to obviously highlight the word documentation. But we have a group of people called a core team at GitLab. And I think a lot of open source communities like BJS and Ruby and others have a similar concept. It's basically, it's to recognize people who have made sustained contributions to GitLab community over a period of time. And what we stress here is that when we're talking about contribution, we're not just talking about code contributions. We're talking about contributing to our forums, contributing to our documentation, UX translation and other improvements that you help make to the GitLab community. So these people get nominated and selected by existing core team members. But wanted to stress that documentation is spelled out there. It's one of the important contributions that we look for. And one of our core and core team members actually, it's not shy about sharing with others that, you know, most of his contributions have been on documentation, which is valuable, not just for the docs, but he also works for an organization that's enterprise user of GitLab. So his feedback as a heavy user perspective is extremely important. So we definitely appreciate that. So I think that's what I wanted to talk about in terms of GitLab. I'm going to try to wrap this up in a couple of minutes. I do see a few questions that come in, which we'll get to in a second. So just to, sorry, I forgot to hit the advance button. Just a summary, and I think both Sophie and I kind of emphasize as having a consistent process with the rest of your project and then having documentation be a key part of your core offering. You know, we talked about a number of important reasons why that's important. But one thing I wanted to touch on is that if for whatever reason, I mean, unless you have a very good reason of having a process that's different, for example, between code and documentation, the risk that you might run into is that, I mean, code gets for software projects, including open source projects. I mean, code gets a lot of attention anyways, right? But so if the process for documentation is different, there's a risk that it's not going to look like a first class citizen because it's going to look really odd. I mean, if you tell people that documentation is key to your project, but the process for contributing where the documentation folders are located is different, then you certainly, you might certainly run that risk of, you know, not looking like a first class citizen. So that's one of the things that I wanted to mention. And this may sound obvious. As Sophie mentioned earlier at the onset, people get engaged in communities through documentation. So obviously that you want to make that first step easy to either join the community or contributing. So if you don't have that, you know, process of documenting or contributing to documentation while documented, you're going to be pretty hypocritical. So you want to make that initial experience very, very welcoming and easy. So that's the third bullet there. And the final point, you know, the easy way to sort of make sure that people recognize the importance of documentation is through things like simple things like documentation, the simple things like recognition. Like, I mean, you know, go through the effort, making an effort to recognize people that have made significant contributions to documentation. I think it'll go a long way. So I'll pause here. It looks like we've got about less than five minutes left. And I see three questions here or more than that. I think Sophia will be on screen pretty soon for the Q&A. All right. So Sophia, so I think the first question from Norris, hopefully I'm not butchering the name. Tips on structuring documentation. Do you want to cover that if you don't mind? Sure. I would say less is more. I see projects that ends up wanting to do everything from the start. And I think that you will probably thank yourself later if you look at it and who is the target for this project or product and the documentation and have some basic installation, basic configuration, maybe some high level overview, and then you can build on that instead of trying to deep dive right away and make it super complicated. Yeah. I would say that's a good start. What do you think Ray? I think you answered it. I mean, I think the only other thing I would add is that obviously it evolves over time. I mean, just because you set like a one structure as a project evolves, I think it will evolve. But I think that's where consensus and feedback from the community is important. Good question. Thanks for the question. And next one I think I'll take is from Beth. Developer time is a concern whose employees contribute to open source. How do you address this challenge with documentation? That's an excellent question. I mean, Sophia, you can probably answer this question as well. But I know this is not easy. It's a difficult thing to do. But I think on a regular basis, you need to campaign for the fact that you need to reserve capacity for documentation, whether it's done by developers themselves who are contributing or getting additional resources from the company, like including like a technical writer is from your organization that can also contribute to the open source project. I think it's one way to do it. But I mean, Sophia, I don't know if you want to add anything there. No, I think you covered that pretty good. Yeah. Cool. And I think next question from Brandon at the start of the open source project. Docs might be a top of mind. How do you make Docs a priority from the start and help sure the Docs protocols and standards are followed? Sophia, I'll let you answer that. Yeah. I think it's a good question. It's a valid question. As I mentioned, not having projects to get away with not completing their documentation is basically you need to have the TSC. You need to have PTLs. You really need to have people be individual advocates for the importance of documentation. I think that you just need to be super tough from the beginning that Docs is a natural part of what we are doing here and the whole software package that you are delivering. All right. I think I'll take the next question from Cornelius. How many contributions do we get from this page link? The answer is I actually don't know. I mean, that's actually an excellent question, and I'll look into that. I can probably talk to our marketing and Docs folks and see if we have that stat, but that's a very good question. Fortunately, I don't have an answer, but I think we have about 20 seconds left. Sophia, do you want to take Matthew's questions about more details about Docs hackathon? Sure. We came up with the idea because Docs is always done in the very last minute, and then we figure what can we do to get projects to start earlier and make it a bit more fun. It's all about hacking. It's all about code. Let's make a documentation hackathon. It's always focused on the upcoming release, and we basically just get together and we sit and we hack or we write Docs the whole day, and it can be new projects that needs to get their toolchain running and get everything done in their repo. It can be just working with content and we talk about stuff and we do it together, so we're making a more fun thing out of it. I don't know if there's too much more to say, but people really call into this and they do appreciate it, and yeah. I think we probably take one more question that's somewhat related from Laisa. Is there a name for the hackathon or is it just called Elephant Docs hackathon? I forget the name of it since it's been a few years for me, but... Yeah, it's just documentation hackathon. There is nothing fancy. Yeah, I assume that's... Yeah, these are per project, so it's not like an Elephant thing. I'm not sure if all projects have the same release cycle, so we have one for OpenFV and then we have one for own app. I don't know if other projects are doing it as well, but it's on a project level. Cool. Yeah, so obviously go to the project Wiki pages. I guess it would be a good place to start. Yes, good point. Cool. All right, well, I think we have to unfortunately cut it short. I think we got like three questions that are unanswered, but we'll hang around in the Slack channel. So if we haven't addressed your question, please feel free to ping us, and we really appreciate your time. And especially you, Sophia, it's like 11 o'clock over there at night. Thanks for everybody else. Thanks for participating. Thank you so much. Thanks. And thank you, Ray. Yeah, thanks.