 Hello, welcome to Contribute to GitLab documentation tutorial. My name is Ray Paik. I manage the code contributor program here at GitLab and I'm honored to be here with two of my colleagues from the technical writing team, Marcel and Russell, who you'll hear from later in the presentation as well. So we'll cover a few items here in the agenda. I'll cover like the first three topics that are listed here. I'll give a brief overview of the why you want to contribute to documentation at GitLab and how you get started. And then I'll turn things over to Russell, who will go through, show you the detailed steps on how you actually make contributions to GitLab docs. We have these steps listed in one of the slides, but he'll actually go through a demo of the steps you need to take to make contribution. And I'm sure you'll find it very helpful. And then he'll turn things over then to Marcel, who's going to also talk about some of the tips and tricks. I think it's like Style Guys and other items that as you start or continue to contribute to documentation, you'll find helpful and how to get help and other items and he'll help wrap things up for us. So without further ado, I'll just move quickly into a quick overview of the GitLab community. Several weeks ago, we celebrated surpassing the 3000 contributor milestone in the history of GitLab. So we're very excited about that. And as you can see from the chart on the right-hand side, we just about doubled the number of contributors between 2018 and 2019, which was really exciting. So if you haven't contributed before and you're joined our community, first of all, welcome. But I also wanted to point out that you're joining a community that's been growing over the past several years. So I'd like to welcome you once again and hope to see a lot of you starting to contribute to GitLab docs and other areas of GitLab as well. So why contribute to documentation? And some of these points are relevant for not just for GitLab but other open-source projects as well. Usually when you onboard into a new community, documentation is a good place to start for a couple of reasons. I mean, one is that you typically don't have a lot of dependencies when you're working on a documentation-related issues or you want to enhance the documentation. As opposed to when you're trying to add a new feature to any software project, you have a lot of dependencies you may have to deal with, things like UX and database and other backend issues. But typically for documentation, you don't have to deal with other software dependencies. So it's a relatively easy place to get started. And you don't necessarily need in-depth technical knowledge of software architecture, for example, if you're contributing to code. So I think it's a great place to get started. And also at GitLab, the process that you go through in terms of contributing to documentation is identical to the process that you'll need to follow or contribute to GitLab code as an example. So once you get familiar with the process of finding issues, getting your merge request triage, review process, and finally getting it merged, whether it's for documentation or code, the processes are identical. So once you get familiar with the process in docs, you're not going to have to relearn or learn something completely different when you move over to other areas of GitLab products. So we think it's a really good place to get started and want to encourage you to get involved in contributing to GitLab documentation. And the final thing I want to say, at GitLab, documentation is a first-class citizen. The way you find where the docs are for each of the projects, you just look for the docs folder or directory and define all the documentation-related files there. So it's the same place in the repo of a project where you find code and other resources for the project. So how do you get started? I mean, this is when you first get started in a new open-source community, like finding things that you can work on or contribute to, it's sometimes a challenge. So I have a couple of examples here that you can follow. And I also already ran this query earlier today, too, so that we don't have to deal with potential delays. So I ran the query here with the labels accepting margin requests and documentation. So you see a list of like 750 issues here that you can look at and pick up. And you can continue to further refine the query to narrow down the list. So I'm going to add one more label here. Good for first-time contributors is another label that we have to highlight issues that we want to encourage first-time contributors to work on. And if I rerun the query, the number should go down way below 748, and we're down to 14. So this is sort of another way to look for issues that you can help us with. So I encourage you to sort of play around with the queries and to narrow down on the list that you might be interested in working on. The other item, I mean, finally, the other item I wanted to quickly point out was that if you want to start working on like improving documentation, you don't need to have like an associated issue like attached to it. Like if you want to start submitting an MR right away, like you don't need to go through the process of looking for an issue or opening an issue. So if you have something quick that you want to contribute to, just start working on an MR and ping us to get our attention. So I just wanted to point that out really quickly. And go places to start. I want to point out a couple of things here. So if you go to any like a documentation pages under docs.gilab.com, at the bottom of each page, you'll find this like a highlighted areas in the purplish color called help and feedback. And you'll see this link that says edit this page. So if you click on this link, you'll be taken directly to the page where that documentation is. So you don't have to hunt through the directory structure or folders to find out where that file is. You'll take you straight to that page and I'll like demonstrate that really quick. So here is main docs.gilab.com page. Like I said, if you scroll down, you see this section here and then click on this edit this page link and it takes you directly to that file. So we want wanted to sort of make that easy for people who wanted to contribute to our documentation. And in just a quick thing, you'll also find the edit this page link at the bottom of each of our web pages. Like if you go to any of the pages under about docgilab.com, whether it's a partners page or community page, if you see something that you want to help us improve, like click on that link and it works the same way as this documentation. So I'll stop there and I'll turn things over to Russell who will walk you through the steps on you know, how you actually contribute to gilab documentation. All right, off to you Russell. I'm Russell Dickinson from the gilab technical writing team. Everyone's welcome to contribute to gilab. In this demonstration, I'll show you how you can contribute to the product documentation. You'll need a gilab account. So if you don't already have one, go to gilab.com and click register. Fill in the details in the form and click register again. To simplify this demonstration, I've already created a personal gilab account and logged in, but you'll be prompted to log in when needed. So let's assume you're browsing the gilab documentation and you see something you'd like changed. Maybe something can be better explained or you notice a mistake. There's no need to first raise an issue in an issue tracker. Instead, you add a copy of the page and ask that those changes be accepted into the main gilab project. In gilab terms, you raise a merge request. In this demonstration, I'll fix a spelling error, but the principle is the same if you wanted to make a more significant change. So in this case, I'm browsing the gilab documentation style guide and I noticed that the word following here is spelled incorrectly. So I want to submit a correction to that. So I scroll to the bottom of the page and at the bottom here in the help and feedback section, click edit this page. That loads the file in the gilab editor. It's got two editors, the basic editor and the web IDE. In this case, I'll just use the basic editor. So I click edit and it opens the document in edit mode. Now the text input field is already focused. So I want to find the spelling error, control F and do a search for the spelling error. Having found it, I'll correct that spelling error and then I can scroll to the bottom of the editor outside the focus of the text box. And what I first need to do is to provide a commit message. This is a brief description of why this change is being made. That is the motivation of the change, not an explanation of what's been changed because that's already available for anyone who's viewing it using the git. So in this case, fix spelling error in style guide and it's important when the commit message for the full stop. Now when I click commit changes, I've already created a fork or a copy of the GitLab project. If you don't already have an existing copy or again a fork of the project, one will be created. But in this case, because I've already created a fork, it's noted here that a new branch will be created in your fork and a new merge request will be started. So when I click commit changes, I'll create a new branch containing the changes that I've made and it will open the merge request form. Just wait for that to open now. Okay, so let's open the merge request form and you'll notice here that in my personal namespace, I've got here the fork of the GitLab project and this is the name of the branch. So this merge request is requesting that the changes in that branch be merged into this is the GitLab org namespace and the project and the branch, this case master. Now it's copied the description of the change message into the title here and I need to provide a description. Now we've got some template descriptions already available within the GitLab project. So from this drop down, I'll select documentation and click apply template. Now it does populate the description with quite a lot of text. Most of that is of use or of interest only to the GitLab technical writers is what I can do here for the moment for the purpose of this demonstration is remove the comments here at the very top and then I can describe briefly what the merge request does. So in this case, again, I can say fixes spelling error in style guide and I can leave it at that for the moment. So I scroll down. I don't need to worry about any of these fields at the moment. I can click submerge request and the merge request will be created. So just wait till that completes. So here's the merge request. Its current status is named up here is open. It's open just now by me and I've got a badge here that this is my first contribution to the GitLab project. It's got the description here. Got various details and again, quite a complex description, but we don't need to worry about that. So from here, this is all you need to do in order to raise the merge request. What will now happen is someone within the GitLab technical writing team will notice the merge request being formed of its creation. They'll then review it and if it's acceptable as it is, it will be merged and you'll be notified. If it needs any further work, again, someone within the team will provide comments and you'll be notified of those comments generally via email. You can also view those comments, of course, within GitLab itself by revisiting the merge request and you may want to make note of that URL. Otherwise, you can find the merge request by doing a search. So again, if there are any further changes to requested by the GitLab technical writing team as part of this merge request that we noted in the comments, you can respond to those comments and once you've reached the resolution on the merge request, the merge request will be merged and that's pretty much the docs contribution process complete. All right, thank you for your attention. Bye. Hi, my name is Marcel Amiro and I'm also a technical writer with GitLab and I deal mostly with CICD documentation. I'd just like to go over some final points and review what Russell did in his demo. Let me start by sharing my screen. So as Russell went over, you have to make sure you create a GitLab account first and once you've found a doc page that has something that can be improved or changed, you scroll to the bottom and click the edit this page link at the bottom of the page. After you make your changes, if you have not created a fork for the project, you will be prompted to create one when you click the button, but that's a quite an easy process and if you've already created a merge request, the fork should already be created. After you've made your changes, write a commit message and click commit and following the steps you can create the MR or merge request just like Russell said. One thing that we didn't go over is going through the review process, so I'd just like to go over that quickly. So if we look at Russell's merge request that he created, you can see it is exactly as it was when he left it, but if you look below, you can see that Ray has actually grabbed this. He's added the documentation label and we have a group of labels over here that'll reflect the type of work that was done and usually the type of document, it could be, it'll be assigned to different groups depending on the labels, but Ray has looked at it and he said, actually, this is fine. We can look at the changes here and see that, yeah, he added the I fixed the spelling and everything is good. So Ray approved the merge request and he merged it into the documentation repository. If there was something that he'd like changed, maybe an alternative spelling, maybe it was a big merge request. He'll probably forward this to a member of the technical writing team and they will then look at it more carefully, possibly make some suggestions and send it back to you by pinging the contributor within with an app mark and your username and let you know, hey, we'd like to do this in a different way or maybe we'd like to restructure it and after hopefully one round or a couple rounds of reviews, everything will be ready and we'll be able to merge it. Some important things is that we have two important guides. We have a general guide to documentation and we also have a style guide that represents the GitLab style. So if I go to that page, the first one, the documentation guidelines has a bit more technical information about how the doc site is generated. You can see that there's information about the different projects that we have documentation for, but one thing that I'd like to jump down is to show that it is possible to actually preview the changes that you make locally, which is very interesting. You'd like to read it. We also do a lot of testing. So we have some details about testing in here. If you go to the style guide, this is quite a large document, but it goes over in fine detail all the various standards that we use for documentation. So if you look on in the right bar, you can see that we explain how to do lists in the GitLab style, how to do tables, how to do links, and it's quite large. There's quite a lot that you can learn about, but when you're first starting out, you don't need to know all of this and you don't need to read through every single little point. Making typo changes, making just changes where you just editing text is fine. And if there's anything that is different from the style guide, the technical writer who reviews it will be able to explain that to you. And often we don't need to change anything because a lot of our contributors are very good at writing. One thing to mention is that there are commit message requirements for GitLab employees. When you're submitting from a fork, we don't check the commit messages very carefully, but we would like it if the commit messages are not too long. At least three words and explain what's happening in the merge request. It doesn't have to be very wordy, but just give a little bit of detail to make it easier for the reviewer. If you need to give a lot of detail, add a title, a blank line, and then you can write as much as you want in the body below that after a blank line. Another point is that we test all of our docs in the CI CD pipeline. So if we come back to Russell's merge request, if you scroll down a little bit, you can see that there's actually a merge request pipeline that ran and it went green. So what happens is we have a bunch of tests that make sure our documentation renders properly, follow standards as much as possible. So it is possible that you make a submission and this will not be green. It'll be red. It's usually because of perhaps a link style that the tools have detected won't render properly. It could be something about a list again that might not render properly. It's generally structural. If it's red, you can click on it and at the bottom it'll give you a message about what needs to be fixed. If you're not sure, you can just contact the reviewer who's looking at your merge request and they'll be able to explain what needs to be fixed or possibly just suggest it directly in your merge request. Finally, once you get comfortable making changes in the UI like in Russell's demo, you can actually start making changes locally with an editor. I use VS code. A lot of us use VS code right now. So it's very much like engineers. If you are using the editor, there is a big advantage. There's more to learn, but once you have it set up in VS code, let me bring back the documentation guidelines, and if I come back to testing here and local linters, we do use two tools called markdown lint and veil, which run various tests. If you are interested in trying this out, you can actually configure your editor to verify veil and markdown lint and veil so that any issues will be displayed directly in your editor even before you submit anything to GitLab. If they say, oh, this link style doesn't match the style guide, it'll highlight it in red or yellow or blue. It'll also give suggestions saying, oh, actually, if you're using this particular grammar tense, maybe you don't want to use that, or this is not a word that's in the dictionary. There's a lot of different tests that'll help you get your first submission merged faster. If you have any questions, I believe this presentation will be shared, but you can go to the contributors Gitter channel and ask questions. You can also find the technical writing team members and their assignments on the team handbook page so that when you create NMR, you can at message them directly. If you don't know who, you can just at message the entire team. So just to show that, for example, one final example, this is the CI CD pipelines page. Maybe I found a mistake. I can scroll to the bottom and edit this page as per usual, but before I start making changes, I can actually see at the very top that there's some extra data, and it says it's stage verify group continuous integration, and there's a link to the team page right there. You can use this link to go to the team page, the technical writing team page, and go to the assignment section, and it'll show who is assigned to that. So if you remember, that was verify continuous integration. So we can look for verify continuous integration, and it's me, that's the technical writer, so you can ping me directly in the merge request and say, could you take a look at this? We also have a backup if I'm on vacation, but normally you can just ping the person directly. Again, if you're unsure, please ping the team, and one of us will make sure that it gets reviewed. If there's other issues that you need help with, or things are slow, we do have merge request coaches who can also help out with your merge request. Not just writing, but also code changes if that's something you're interested in doing as well. For any other questions and feedback, you can send an email to contributors at gitlab.com, and we'll get back to you with an answer as soon as we can. I'd like to thank you all for being interested in contributing to the GitLab documentation project. I myself was a contributor before an employee, and it was a really satisfying and enjoyable experience, and I hope you enjoy it as much as I did, and as much as I do now. So yes, thank you very much, and I look forward to seeing your submissions in the future.