 Okay, welcome everybody. This is the Fedora Atomic Coast Documentation Workshop. We are here to do some things to, we are here to add to the Fedora Atomic Coast Documentation, which needs a lot of adding to, because there's barely anything there right now. So, here's what we're going to be actually doing during our two and a quarter hours here. I'll talk a little bit about the new docs repo in-site, and then Tristan is going to give people a crash course in ASCII Doc and ASCII Binder, and then I'll show you briefly building the docs for anybody who wants to actually build the docs to test, and then we are going to write some documentation, and then we will have some fabulous prizes, and we will sync up about the documentation that people have written, so pretty straightforward. So, one of the things that Tristan and I created about six months ago, was it six months ago or so? Yeah. It's this Atomic Host Docs repo, because previously, and here we can actually see, here's the Atomic Host Docs repo, because previously all of our documentation has been on the projectatomic.io webpage, which uses middleman, a static site builder, and that sort of thing. This is not a documentation tool, and it's really shown. It's hard to organize and maintain. It's very difficult to navigate. Not a very good thing. So, we wanted to actually move the docs to an actual documentation tool, and separate them from the public website, also so that we can actually produce documentation in another format, so like a PDF and maybe a help file and something else. So, this is what we're doing at Atomic Host Docs. That is, by the way, github.com, projectatomicatomichostdocs. Please go ahead and clone that, and if you cloned it yesterday or something, please do a get pull, because I just discovered a bug in the topic map this morning and fixed it. So, go ahead and clone that. Preferably, if you're planning on contributing, go ahead and create a fork on GitHub, so that you can later on submit a pull request. So, here are the things that are different about our new docs repo. So, this is going to be published to docs.projectatomic.io. It'll be built with ASCII Binder. ASCII Binder is a new-ish documentation format. The important thing about ASCII Binder for us is that it's used by other Red Hat projects, most notably OpenShift, and so it allows us to combine efforts with documentation people on other projects that we interact with anyway. As a matter of fact, particularly, well, you'll see in a minute on CICD and that sort of thing. It's going to be hosted on OpenShift Online as a site there. And right now, what we're working on today is what we call the administrator guide. It's all about how to administer an atomic host system. At some point down the line, we also want to create a developer guide, but we don't have a specific timeline for that. So, one of the other things that we plan to do with the new docs repo that is not quite together yet because there's some tooling issues we're still working on is to do continuous integration, continuous documentation. As in, even more than code, it makes a lot of sense that documentation publishing for an open-source project should just be mostly automated and happen continuously. So, the idea is in the future for the atomic host documentation, what happens is you submit a pull request to our GitHub repo, the pull request gets sent off to Jenkins. And this is one of the areas where we're missing tooling because the ASCII binder testing tool is not finished working on that. But it gets submitted to Jenkins. If it passes, then we go ahead and send a message to an OpenShift build system. OpenShift build system will then create an image containing the static version of the docs based on building the ASCII binder that will get shipped off to OpenShift's online pro account and will become the new version of the docs. The idea being that all that needs to happen is for somebody to approve the pull request and then everything else is automatic. Anybody else want the container? So, in addition to making it easier for us to produce the documentation, the other idea is that this is a good way to introduce people to a very lightweight form of continuous integration compared to what we're going to be using to produce atomic host itself, which will be much more complicated. That was not supposed to be a slide. So, given that those are our plans and this stuff, the new site and everything, we're looking to have this up somewhere in the middle of October. Like I said, not quite ready yet because of some tooling stuff. But I'm collaborating, we're collaborating with the OpenShift documentation folks who are building the same exact tool chain. So, we'll have one tool chain that will work for both. Let's talk a little bit about the formatting for the docs and mainly the ASCII doc format. So, do you need to plug in or because I can also just flip to one of the documents? Do you need more than that? Yeah? Okay. Okay, got any team either? So, ASCII doc is a plain text writing format. Not really like markdown, few syntax differences are there, but it's just like plain text. So, ASCII doc, what it does, it converts that ASCII doc text files to HTML or you can create a doc book from it. So, ASCII doc is the tool for converting ASCII doc to HTML. And ASCII binder is a system build that helps to maintain these docs. So, this is basically for maintaining and contribute for the easier purpose for contributing to doc. So, but the main tools are ASCII doc and ASCII doctor. So, we are using three of this for the atomic host doc. And I'm going to show you how we use it. We have on the main repo, we have distro map YAML file, which has this kind of format, means the name of your host, I mean the title, and the site URL where you are trying to host your doc, this kind of thing, and the branch where you are building Git branch, this is where I'm building the doc. So, we are also aiming for Fedora and Centric atomic doc. So, that is why I have currently commented this out because there is no such scope right now. We are just focusing on the project atomic doc right now. So, this, you will be able to show this, I mean, see this when you build the doc, just let me show you. So, after you build this doc, it looks like this. So, let me zoom it. So, if you look at the distro map, you see the title of the product is atomic host, that is the name. So, when you build the doc, you just replace the build system, just replace the product title with atomic host. And wherever you need this product title, you just, I mean, it looks like a ginger template, you have the double second bracket, and under there you put the product title, wherever you want to write your product title, you just write that thing in your doc. So, distro map is just for that thing. And the next one is topic map YAML file, which means this is the main file where you write all the directories and file names, that is, which is, which the AxiBinder is going to build. So, let me show you an example. So, here the topic is cluster setup. So, if you look at this build, you have the cluster setup here, and when you click on it, you get all these sub-topics, which means you have the sub-topics here, Vagrant, OpenShift Origin, Kubernetes, and others. So, I think you can connect the dots right now. And so, basically it is, you have the name of the topic and the directory. So, if you look at the file, here is the directory cluster setup. And if I do LS, you will see the directories, again, Vagrant, Kubernetes, OpenShift Origin. And let me browse the Vagrant directory. And you have the multi-node and single-node doc. So, here is the multi-node and single-node doc file and the topic of the file. So, after you build the doc, it looks like this, Vagrant. And under the Vagrant topic, you see the sub-topics, single-node, multi-node. So, I have, so currently we have, currently we have an outline to achieve this documentation right now for the project atomic host documentation. And I have built the topic for all these files and directories in topic map.yml and created doc for it. So, what do you need to do just now? I hear, you do not need to, I mean, care about this file right now unless you see any error during the build. And just, you need to go ahead and choose a file. So, if you want to write a doc on introduction, so let me suppose, introduction goals of atomic. You just go to the directory introduction and write the goals file, because the doc is already built. You just need to put the content there and we are done. That is how, any questions on the ASCII binder or how it works? So, there is already, I think, few doc build. Like, if you look at the contribution guide, it has the syntax like how to write the ASCII doc. So, suppose you want to create link, you need to follow this syntax. And this is the code block. Suppose you want to add some code block. This is the syntax. You just need to put four dots at the start and end. And this is kind of subtopics and topics. So, when you go on putting this equal sign, it creates subtopics under the topic. And this is for bullet sign, which is like markdown and same of a code block. So, if you look at here, I have added product title here. So, when I am going to build the doc, the product title is going to replace by the name. I have put it atomic host in distro map eml file. So, this is why I think I like ASCII doc much than markdown. So, this is how we, this is the syntax. And there is a, I think, link for the ASCII doc syntax as well. I think this is the link. I mean ASCII doctor. Here it is. I think this is the link, right? For the syntax. Yeah. Yeah. So, if you are stuck with syntax, you can just look into this URL and look for the syntax. Also, the contribution guide gives you an example of a lot of the likely stuff that you would need to use. There are examples there of a lead of sub headers, of code blocks, links, and there is an image. So, if you use that as sort of your example of how to do the elements of syntax, that will work well. Although, the emphasis here, by the way, is getting the content out. Because ultimately, if you get the content down on a page, we can get somebody else to fix up the syntax. So, the most important thing is to actually kind of get the content transposed over. Okay. Right. Are we ready for the rest of the stuff? Yeah. Okay. Plug back in. Oh, come on. There we go. Okay. So, now, again, like I said, you can actually do this workshop and that sort of thing and just write stuff in your text editor and not actually run it through ASCII Binder to check it out. But in case you do, there's two ways to install ASCII Binder. One is natively. That is, if you're okay with, you can install the package for ASCII Doctor followed by the, well, and I'll show you in a minute how to do that. And so, natively, the past package for ASCII Doctor followed by the Ruby gem for ASCII Binder. Or you can do what I do, which is run it as a container because I hate installing things on my desktop, particularly Ruby. So, I actually run ASCII Binder inside a container. The, now that contribution guide that we just showed you actually has instructions for both kinds of installs. The, for those of you who, I did the container, like particularly if you copied the container from the USB key, let me go ahead and show you how to use that. So, the first thing you would actually need to do is go ahead and load this. That was a Docker export for the container. So you would do Docker load ASCII Binder image and that would put that in your image repository. Then you switch to the repository path. And then the rest of the commands, you treat that as sort of a binary to run ASCII Binder. But you need to bind in your repo directory. So that's the command line from the contribution guide. This is actually just doing it in preview mode. So I just send the ASCII Binder command. That'll go ahead and run. It'll give you a whole bunch of warnings. The, keep in mind, because ASCII Binder works with Git branches, it will actually do the, it will actually do a check-in on Git, which means you'll get Git messages, which means if you have unsafe changes, you can get, it may stash them. But, so once that's built, then you can actually browse it to see how it worked. So, for example, so, wait, no, that's not what I wanted. So the preview will be under this underscore preview directory. Don't worry, the git ignore that we ship as part of the repo already says don't check that in. If you go into the preview directory, we have a whole directory tree that includes everything out in HTML format. And so here's that contribution guide in there. And you can see the navigation for all of the documentation. So this is what we're trying to produce. So, oh, and the other thing about this contribution guide is if you want to do the native install, the native install documentation is there. So, I mean, you can read the ADOC source file directly. It's pretty readable. It's there. So, so now it is time for us to write some documentation. And here's the way that this is going to work. We have a set of issues that have been created on the Atomic Host Docs repo. These issues are tagged with flock. These are all missing documents that need to be added to the documentation. The issue has been named after the tree location in there. So this using OS tree, OS tree compose, if you actually, that's looking for right here in the tree. So that should match the tree location. That's missing an intermediate layer there. But that should match the tree location, which also matches the directory tree. So if you go to using OS tree right here, and then you will have a document called OS tree compose that is empty. Now, one of the questions is, you know, how am I going to write this? Well, in the case of a lot of documentation, including pretty much everything that you're likely to work on today, our team in VFAD went through and hunted for existing online resources and stuff we had in the documentation, which already supplied, had in some other format, most of, you know, some or all of the information we wanted to have in the doc. So like here for OS tree compose and that sort of thing, there's some blog posts and a bit in the attic, and I'll show you the attic in just a minute, that already have some documentation about OS tree compose. And so what we really need you to do is to take that other information, copy out the portions that are appropriate to the document that you're working on, you know, integrate them together and fix the formatting so that we have a document there. The, so in terms of the attic, so that's actually part of the atomic host docs. So we have a bunch of material that we got from elsewhere. One of the biggest ones is the rel atomic guide. And we've copied these over here for convenience. So these are all the documents from the rel atomic guide. They are already in ASCII.format. However, you know, structurally, they don't match the contents as we want them a lot of the individual content, both because it refers to rel and because it takes a different approach towards, you know, how to do things needs to be edited. And, you know, their coverage only covers about, you know, 20, 30% of all we want to cover. But so this is where the attic is, if you see in the issue that something refers to a document in the attic. And so that'll be in the get clone that you did. So now let's do some opportunistic locking here. You know, let's get this. So in order to prevent conflicts, when you choose a document, it would come up and just write in a abbreviated form in the name of the document here and put your name on it. I can claim them in GitHub, but you'd have to obsessively refresh, though. Oh, assign them to yourself. The problem is that it won't prevent somebody else from, from how, GitHub is opportunistic about conflicts. If you assign it to yourself, and I assign it to myself, whoever gets in last is going to end up with it assigned, but you won't necessarily see that. So, and there are all issues on GitHub. Yeah. Okay. If you want to do that. Yeah. Okay. Oh, okay. Okay. Well, we can, we can try that. And we can see if people claiming them GitHub works. So just to reinforce that, though, speak up and say what you're taking. Since we are all here in this room, and it can be synchronous. And so the idea is you'll work on that document. We have, what time is it now? Quite a while. It's 10, 10 right now. So work on that document until, we'll be working on documents until 1115 or until you get done with a particular document, if that's sooner than that. Then I want you to partner up with somebody else and that person will review your document. And then we'll do that for 15 minutes. And, you know, and then we'll finish a little bit early for lunch. It's a long time to sit in the room. So one last thing before we get started writing. Of course, because this is one of my, because I'm here for this workshop, we have prizes, fabulous prizes. So I think we need to do some, some prizes for stuff. People have seen me wearing this Project Atomic Fleece. I ordered a few of these. So whoever does the most or the longest document today will get a fleece. And then if somebody decides to take on writing an original document, rather than one that's copied and pasted from somewhere else, one of the ones that we just really have no resource for, we'll go ahead and give them a bottle of Atomic Hot Sauce, which, you know, you need here in Cape Cod because the food's pretty bland. And then, actually, do we have anybody in the room who is not a Red Hat employee? Awesome. You're going to get residency. You're going to get all the swag because if you, if you finish it, if you get most of the way through a doc at all, we will give you the outside contributor hat. We want you to feel valued. So we're going to load you down with swag. Okay. So go ahead and get started. And we're here to help. Sean is here to help in terms of helping writing docs. And let's get some of this documentation knocked out. Yeah, sure. Anyone who doesn't want to use container or set up locally, here she can use the playbook here. Just run the playbook. Just make sure you have Ansible installed and Ansible playbook set up YML file. Just run this playbook. It's written in the contribution guide. You can read the contribution guide if you have doubt. So there is a Vagrant doc which has the header. So if you're going to add doc, you can, this is the template where you can add this kind of header in your doc. So this is the product author, product version, product title that we have in distro map YML. So this is the header you need to add in each doc. Product title in the distro map, which in this case is going to be atomic. The problem is you're already there, but I had the whole team listed as having right permission instead of admin permission. So I've just fixed that. Well, your browsing history should go with something else. But there's a bunch of these where he skipped the middle level. And that's science. You can blame him for that. So that one. So it's at the top level, but the top level was like, like that was the sub padding, right? It should have been using OS trees. No, just using OS tree slash updates. The browsing history should be using OS tree examining your system browsing history, except that those docs are already populated. So okay, I'm actually to update those. I actually need to update those. Like performing updates. Is that what that means? He already opened a pull request for that one. Yeah. But in his pull request, I'm gonna ask him to look some more stuff. Okay. All right. For the sake of this one. Isn't that what that tells you right above this scroll up? Oh, okay. Yeah. Yeah. But just over determining. Okay, cool. So can we add more clarity performing updates? Is that what we mean? Yeah. Like doing a RPMO tree upgrade? Yes. Okay, got you. All right. Yeah. The earlier the original title see using OS tree section to docker. I don't know what what they Yeah. So can we add it just make it performing updates? Well, that's not that's not the header on the TOC. So just put this is about the directory structure is wrong. Yeah. The directory structure matches the outline, which is is wrong. What? No, I'm looking at the directory structure of the docs repository, which is wrong because the outline was wrong. And again, it's because it is indenting thing. And the problem with relying on indenting is that because GitHub uses markdown, it's smart about markdown. So sometimes it fixes your indenting. And GitHub markdown doesn't actually support indented lists. So it'll mess them up. And we've had this problem a number of times. So basically, this is this is the OS tree documentation. This doc right here OS tree mutation that's supposed to be directory, not a document. Yeah. That's a directory covering overrides package layering and live FS. Yeah. So the admin and lock should actually go in this overrides documentation. The overrides page for overrides, there should be. Is there not? Okay, in that case, well, I actually wanted separate issues for each of those docs. I've been here. Yes, he's got one here for, wait, there's one for live FS. What's missing is the override stock. So actually, let me just rename this one overrides because that's what we really want there. I need to shrink this because I can't I can't operate scrolling around. I'm not going to fix the directory structure because I would just mess things up further. Oh, merchant changes person. Well, we're about to do the review segment in about five minutes. So yeah. Yeah, we don't have one right now. And that wouldn't necessarily be a bad idea. I just I'd actually have to look at hold on. All right. Okay. Well, thank you very much folks.