 So a quick introduction on my side, my name is Justin. I'm a member of the Fedora DNI team, but I've also been pretty hands-on with the Fedora docs project too. In 2018, we had a docs fad where we did a lot of stuff about how we think about or thinking about how we organize our docs, thinking about the tools we use. And so over the last two years, a lot of the Fedora documentation, which was previously in a doc site or in the Wiki, we've now started to move over to this ASCII doc-based publishing mechanism. The tool chain is called Antora. That's what's actually doing the publishing in the docs, but we're not going to get super into that. What I'm really gonna be covering in today's talk is, there's not really a talk, it's more of a shadow session. So I am gonna talk a little bit about how the DNI docs are structured, what things we're publishing there right now and a little bit about our docs efforts from over the years. Then we're gonna do two different screen shares. The first one is going to be editing from the web browser. So you can edit these docs straight from Pagore. The second one, which if you wanna stay for, it's totally optional. If you just wanted to get a quick introduction, but the last part of this is going to be more advanced, where I'll be working in the command line, rendering the docs locally. So if you're interested in that, stay tuned and we'll get to the more detailed hands-on part towards the end. So I'm gonna shift over to my screen. If you're in the hop-in chat, you can double-click on the screen share to make it go maximized or full-screen just so it's a little easier to see. So the page I have open here right now is the Fedora docs site, which I'll go ahead and link in the hop-in chat. Not much to talk about here, other than this is where we publish our docs. You can see we have a couple of different pages. This page is our landing page, our index page, where we talk generally about diversity and inclusion in Fedora broadly, some of the things that we've done. So page about the team that talks a little bit about a little bit of overlap, actually. We have an issue open for that, which we'll be talking about. But there's also other pages, like we have a page about all the events that we've done over the years and some of the outreach we've done. We also have a lot of notes from the demographic survey that we did at our 2017 HackFest and also things about Fedora Women's Day and how to get involved with the team, things that are helpful, like a meeting, like we have a meeting script, if you wanna run a meeting or if you wanna get a meeting on the agenda, we put some of that workflow stuff in our docs. So that's great that we have that content, but that's not really what this shadow session is about. We want to try to change some of this stuff, right? So for context, the doc site used to be all of our Fedora, used to all be in the Fedora Wiki. This is from June 2018, so this is like two years ago. The challenge with that was that the Wiki would frequently fall out of date and also it was just hard to connect different pages together, like we have that nice little sidebar where you can click to the different pages. Don't have that in the Wiki. So just for some historical context, like that's where everything used to be, but we're really big on moving to the docs because it makes it easier to organize things and keep up with where all of our different information is, which is easier if you're a new contributor and you're not super tuned into the Wiki. So we are going to be talking a lot about this Pagora repo today. Like I mentioned, it would be great if you can go ahead and make a fork of that to your personal Pagora account. If you are a member of the DNI team, you can commit directly to the repo, but the best practice is usually to work from your own fork. So that's the way I'm going to be showing in this presentation today. So I'm hoping that if you haven't forked the repo yet, go ahead and take a minute to do that, but I'm going to go ahead and jump right into this. So the first way I'm going to talk about editing the Fedora docs is from the web browser. So this is the easiest way, I think, to really edit our docs. You don't have to set up any tools. You just have to log into Pagora and edit. So once you're in your own fork or wherever you're working on the DNI docs, you'll notice that there's this files tab right over here. So if you click that, you can start to actually go through some of the different files in the repo. There's a lot of stuff in here, but there's really only one thing that matters, which is in the modules folder. It's a little annoying, but you have to click through here a couple of times and then you'll see pages. And ta-da, here's all of our docs pages, the actual source content that gets published onto the docs.fedoraproject.org website. So you can open any of these up and it's going to show you the raw source text in ASCII doc format. I'm not going to talk a lot about ASCII doc today, but I will share some links that I always keep bookmarked that help me when I'm working in ASCII doc just to reference the syntax and some of the other best practices, like one of the things you'll see in these docs as well, which is might be different if you've never worked in docs before or in Fedora docs, I should say, but every sentence is its own line. Just kind of a thing no matter what tool, no matter where you're editing, that's a best practice we do for a specific reason because when you go and make a pull request with your changes to the docs, it's a lot easier to review what you're actually changing if every sentence is on its own line. It makes the Git diffs really pretty and really easy to review. So I don't have to spend, not just me, but anybody can spend less time trying to figure out where the line breaks are and it just is easier to review. So just keep that in mind that whenever you are editing the docs, you always want to add a hard return, a new line after every period. So today I'm looking at, so let's look at, I'm looking at the demographic survey page here. So you might have one or two options depending on where you're looking. If you're in your fork, you should just see the edit button but I'm actually in the main repo so it's saying edit in your fork because that's usually the better thing to do. So in your editor or in your web browser, you can go ahead and click that edit or actually I guess I was gonna do the events page in my demo. So I am going to edit the events page and I'm gonna walk you through this page really quick. So I don't think I can resize that. That's a little annoying. So let's pretend that I have, I'm gonna add a new event. I'm going to add Fedora nest shadows session with our docs. And normally I would add a lot more there but this is just an example. So let's say I added more info about this nest session we did. I'm gonna talk through these four things really quick. The first one is the email address which isn't really huge but if you care just remember that this email address is public information so it is public whatever email address you choose just an aside but I'm really gonna talk more about the branch part because this is actually really important and is one of the biggest pain points I see for folks who are doing this. It's the default is to commit straight to master but it's actually a better practice is if you do what's called feature branching and if you split this out into a new branch. So there's a couple of reasons for doing this. One is that from a Git perspective it'll be easier to manage your fork. Like I never commit to the master branch. I always keep my forks master branch synchronized to the upstream repo just because I find you avoid Git conflicts and some of the more painful parts of Git if you can not commit to the same default branch as the upstream. So in this case it's the master branch. So I'm just gonna name this one new nest event. Like it doesn't matter what the name is just do something unique commit title. This is nothing different here but it is important to actually make something meaningful because this is what's going to be your pull request. This is what an actual DNI team member or anyone not just whatever docs repo you're looking in someone's actually gonna read this stuff. Like a real human being. So it's important to write something that's a real human being could understand and make sense of. So I'm gonna say add fedora nest shadow session and let's pretend I added pictures screenshots and summaries of the nest session I did. You don't have to write an essay in here but just something that makes sense something that would actually help someone review your changes or more importantly understand why you're making the changes. That's really what is important to note in here. So okay I did that I did my whole edits. I added all this stuff. If you're working with ASCII doc the first time might be a little awkward but don't worry about it too much. Like that's why we do the pull request process is there's a review process. Someone will actually review your changes and give you feedback if everything looks good and they'll merge it or if there's something that needs to be changed you'll have a chance. You're not gonna be writing changes straight to the doc site. So there is a review process. The team is really friendly. So it's good to double check your syntax and stuff but don't panic if you're not really familiar with ASCII doc. So that's it. We'll do commit changes and Pagora is going to commit my changes. It's actually making that new branch that I made the events nest, what you're gonna call it new nest event branch so it made that branch and you can see, hey, this branch contains one commit that's not in the upstream Fedora diversity master branch and I have this handy button to create a pull request. Yeah, so let's do that. Let's create a pull request and it's gonna take, just like I type in earlier there's my commit message summary there's the commit message description it pre-populates the pull request with that info. You can see I have my super simple change that I'm not going to merge because it's just an example but let's create the pull request just to show what it looks like. So now you'll see it as a new pull request open in the Fedora docs repo for the diversity team. You can see the files change, the commit messages and all of this I did straight from Pagora, the web interface didn't even clone the repo. This isn't really doc specific but on our side for the DNI team usually if you make a change to our docs you can expect that I try to always assign someone if someone's gonna review the change and take responsibility to be the one to merge it. I usually try to assign someone but usually expect like within it also depends how big your changes are or whether you're changing something like a policy on our team which is something that the team all votes on versus like adding an event. If it's something simple expect within a week but there's some of the bigger stuff that I mean, this is just an example and I think really the point is you can expect like for simple changes and just improving the docs it's usually a week turnaround time. So that was the web interface part of this. I will go ahead and do a quick pause if there's questions in the chat about anything I covered in the web interface piece before I move to the more advanced part. And if you do want to jump out now, now is a good place if you wanna transition to something else then the rest of this shadow session is going to be more technical. I'm gonna be working in the command line rendering the docs locally showing how that actually looks. So if you wanna learn that stay right here but otherwise that is the direction we're gonna go next. So I don't see any questions in the chat but I will keep watching that if anything comes up. So I'm gonna go ahead and update my screen share and go to the place where I spend a lot of my time. Cool, so I think I'm sharing my terminal window again. So again, as a reminder if you double click on the screen share you can make that go full-size so it'll be a little easier to see. I'm going to zoom in so you can actually read what's on my screen. So just to get some context really quick I have, if you're doing this for the first time you take it from your fork do get clone and clone your fork going back to that feature branch workflow I talked about earlier. I always add a new remote to the upstream and you actually have to do that like get add remote upstream URL, blah, blah, blah, blah, blah. So, and you can get that all from the Padgor web interface there's that little clone menu in the top right corner that's where you can find this stuff. So this is how I normally like initialize my Git repos is I always have my fork and I always have an upstream the origin and the upstream. So with that out of the way let's talk about the branches a little bit. So I'm going to do the same thing that I just did in that last pull request just to do a pretty easy comparison. So I'm also going to try not to use my aliases because those are not intuitive. So I'm going to make a new branch and I'm on the master branch maybe one thing it's important to do here that I always do before I start working is I always make sure that if I'm in the master branch or the default branch, whatever it is I have the latest changes from upstream. In this case, I did this five minutes before I went on video. So I know I have the latest changes but what that's doing is I'm actually getting in making sure that I have the latest changes the latest commits from upstream. So I do. So I'm going to go ahead and make my feature branch which is going to be Git checkout I'm going to use the new branch and let's say change, I'm going to do the same thing change events, different branch name, but same edit. So I like to use VIM but of course you can use any editor that pleases your heart. I'm not going to talk about this. Ooh translation questions. That's a great question actually and I want to make sure I cover that. So for this edit, I'm going to do the same thing. I'm not going to spend a lot of time in here but you know, go ahead and do the same thing. Fedora, oops. Fedora nest shadow session on editing the docs. And pretending there is a lot more content here. So that's great. So we have that in the events page I'm in my feature branch. So let's say I do a bunch of, I do all my edits. I do all the things I want to do in my text editor of choice. I'm ready to make my pull requests now. So I always do, well, depending how your workflow is, you know, you always have to add the Git page to your staging area. So I've added it, now I'm going to commit it. I always add the dash s flag to my Git commits. Maybe that would, this would be a good, just quick chance to actually explain that. What that actually means, because I get that a lot. So yeah, sign off. This is just kind of this, basically it just means that it adds this line that says signed off by your name and your email to the Git commit. And it's just a way of certifying that you're agreeing that you have the rights that the work you're doing is actually yours. You know, you have the rights, this is your independent changes and you're agreeing to share it under the same license as the original project. Not really important, but it's just a habit I do and people ask about it. So that's why I always mention it. But I'm going to do that now, Git commit. And you can see there's my signed off message, but I'm going to do the same thing here. Added a, or I'm going to say events. Add a nest 2020 session to our events. I'm going to say it was the shadow session. It was great. So much fun. So I'm going to do that. And I have to type in password. Cool. So I made the Git commit, that's done. That's on my feature branch. And now if you're working locally as a reminder, you know, all those changes are still local. I haven't actually pushed those anywhere. So let's actually go ahead and push these changes I have locally to my fork repo in Pagor. So for the first time I do this, I am going to push my feature branch to my fork. Gonna do that. And if you're in the command line, you'll also note that Pagor gives you this handy little URL there. Oh, what do you know? Create a pull request. It knew exactly what I wanted to do. I'm not going to click that because that means I have to change my screen share again, but you would click that up and you would get the exact same pull request interface that I just showed earlier in the web PR part of this talk. Nothing too crazy there, but the last thing I do want to talk about, which was the Docker piece, the containers. So you'll notice that in every docs repo that, you know, there's also this template repo that the docs team maintains. That's kind of the base for any new docs site. But it comes with this build and preview script. And that is how you're actually going to say, you know, we made the changes, but you want to test. This is also really key if you're doing cross page references like xreps. It's a good idea to test your changes because that syntax can be really confusing. So this assumes you already have Docker, Podman, a container runtime installed. So I'm going to go ahead and run these scripts. And you'll see, oh, this build script is using Podman to run in an isolated environment. Da, da, da, da. So it's actually building, it's using the docs tool change, ASCII binder and Torra, all that good stuff. And you see, hey, okay, here's the docs site. So now I am going to have to update my screen share because I'm going to open this in a new browser window. And you can see that I did open it because there's all the web traffic logs. Let me update my screen share one more time. Ta-da. And you might have to double click my screen again if you want to see it full size. But a big thing you'll notice here is local host. Yeah, I'm all local. This is all on my machine. I'm not on the official Fedora doc site. So going to go to the events page because that's where my change was. And ta-da, there it is. And if I was looking at this normally, I'd be, oh, wow, we used bold on all of those. So I probably want to make that bold so it matches the syntax of all the others. One of the great things about testing the changes locally is you can actually see these things and be like, oh, that's weird, I should make that bold. Anyways, if you have issues with that, it's likely, I know I've had troubles with the local build preview before as well. If you have challenges, I recommend jumping into the Fedora docs IRC channel or matrix group. The folks there are really friendly and are really, they do the stuff day in, day out. So if you have troubles with it, come reach out to us there. It's all usually gonna be in the container runtime piece. And this is also true, whether you're working in the DNI team docs or like any doc site, like that was actually something like that build script is something that's bundled in that Fedora docs template project. So this is basically true. If you want to test your changes, this is basically true of any Fedora docs repo. So I would have liked to have gone a little more in detail to maybe show some of the more like interesting stuff, like doing those cross page links and some of the other syntax. If you are interested in those things, I suggest you hang out. If you have a DNI team specific request, just join the DNI team chat and we can help you with the docs there. If you have a general question about the docs, again, plug in the Fedora docs team, Fedora dash docs on free node, I think at fedora underscore docs on telegram. Folks there are happy to help with that, but I won't have time to cover that today because my session, this were officially done in one minute and the keynote is in five. So I'll take a quick moment. I know this was kind of a lot to cover in the time that we had. I hope it was helpful, but I'll take any questions or if you want to come on the video too, happy to answer questions on audio video or in the text chat. Oh, there was the question about the translations, which I did see. I thank you, Eduard and Misk for jumping on that in the chat. I'll just mention, translate.fedoraproject.org. So this is the site that we do our translations on and like very recently, as in the last month, we started getting our docs repos better synchronized there. I don't know what the right way to describe it would be, but again, Jebeck, he's the person who really drove a lot of this, who drove most of this work. He's a great person to ask, but there should be, yeah, you can see, here's some of the Fedora docs repos, like the Fedora release notes. That's probably one of the most important ones in terms of translations because that happens every release. Now, obviously F26 is not really important right now. I guess there's not an easy way to filter old pages from the old, but you'll see if you go probably to the last page, there'll be Fedora 33. This is only gonna be a thing with like the release specific docs, like the release notes. Most docs aren't gonna be structured this way, but this is the release notes. So it's kind of the special snowflake of our docs. But anyways, this is where you can, you can make those edits and translate our docs into your own local languages. So you do that all through the weblate site. This makes me realize I need to make sure that the diversity docs are in here. So that is a great thing that I'm gonna follow up with after this. But generally this is where you'll do the translations and I am personally like, I'm very interested in trying to bring more translations to the DNI team docs because that's, I think it makes a lot of the work that we do more accessible. And we have a lot of folks who do the local Fedora Women's Day events. Like I'd love to get more Spanish content because I know we have folks who are Spanish speakers that use a lot of the DNI team docs. So that's kind of my one thing that comes to mind. And Hindi for sure, as well, because we do a lot, that's the second one. We have South America and a lot of events in India as well. I just know it's trickier with the local languages in India. But cool, I don't want to hold everyone up from the keynote. So I am gonna go ahead and stop there. If you have questions, come say hi. If you have DNI team specific questions about our docs, come say hi in our team chat room. Fedora-diversity on FreeNode IRC or at Fedora Diversity on Telegram. If you have general Fedora docs questions or questions about a repo that is not the DNI team docs, check out the Fedora docs team. They are friendly and nice folks. They do not bite. They will help answer your questions. So with that, I will see you all around Nest and enjoy the keynote. Enjoy the rest of your day. Thanks for tuning in, everyone.