 Hello everyone. I guess we can start. Oh, thanks, Brian. So, my name is Adam Shemalik and I work on the FederaDocs, which we got out last week. And many thanks to Brian Exabier, who basically did half of the work with me. So, that was great. So, what I'm going to talk about today is four things. I'll give you an introduction of the new site, what it is, how it looks like. Then I'll talk about Antora, which is our built engine. We use some core concepts and how we can use it. And then something about contributing and the source structure, so everyone knows how to make contributions. And maybe if you're a working group or a team or someone, you can even move your recommendation in there. And then some plans for the future that we want to do. So, let me start with the introduction. And I'll have some few slides and I'll just show you the site. So, about the sources and building. We have converted sources to ASCIIDoc, which is a very simple markup language. And before we basically did this, the documentation was written in DocBook, I think. And that was XML, which was really nasty to write. And we didn't get much contribution for some reason. And so, we, or basically the people before I joined, were figuring out what to use and ASCIIDoc was the best option. I think they even considered markdown and other things. But ASCIIDoc was one of the things that was basically the best. And in the end, we used Antora, which is a new built engine with an active community that basically takes the sources and builds a static website. And you'll see that in a minute. So, I apologize for this slide. I think I have never written so many words on this slide, but it was late. So, about the navigation, we've built a clear navigation structure that kind of scales well. So, I say that the information architecture has been designed in a way that scales extensively. And this is important because we want to accommodate many different things on the site. So, for example, we have the user docs, but we also have docs about the Fedora project. And we can also run working groups and teams in Fedora in there. I'll show you in a minute how that looks. Yes, we work on translations because this is important because we have community around the world. This is in progress, but we already have the language code in the URL. And I'll talk about the end in the future section. And there is one new thing that's called QuickDocs. And these are basically docs with a specific purpose, describing how to get into a specific goal instead of describing features. So, if you, for example, see a documentation of, I don't know, HDTPD and you can see all the configuration options. Like this, this, this, this, this, this, this. It's kind of hard to start with. So, this will tell you, for example, how to use the web server in this particular way and how to get with it, how to get to it. And there is already an effort putting various Wikipedia and other resources into these QuickDocs. And you'll see in a minute that we need a better UI, but that's also one of the future things. All right, so let's see the documentation. And I'll try to speak in the mic here. All right. So, hope you can see that, right? So, this is the new website. It looks like this. The homepage is quite simple, simple-looking, but I think it has everything we want. So, there is the user documentation in the top and then the community section. And for example, if I want to see documentation about Fedora28, I just click on it and I see all those, basically those three guides we already always had. So, there are the release notes I can click on and just Wi-Fi is failing me, but it'll get there eventually. I get the installation guide and the system administration guide. And now my Wi-Fi just died. All right, there we go. I can also share the QuickDocs, which are kind of messy. So, these are like all the ones we have. You can see why we need the new UI. But they basically describe end-to-end things. So, we will logs in Fedora, for example, or how to create disk partitions and stuff like this, or installing Java. So, these are the user documentation. And we have the two active releases here, the QuickDocs, FedoraRohite, and this will be the link to the old documentation back to, I don't know, Fedora... whatever, I guess one. And here is the project documentation. So, Fedora Project, Fedora Council. And these two sections about engineering and mindshare, which are basically the two major groups in Fedora. And if I open MindShare, apart from some information from what that is, I can see MindShare Team. There's not much, there's just one, Fedora Community Operations. But basically, this is the space where we can list multiple working groups or teams we have in Fedora that are doing mindshare. And they can have their own space here, with their own menu and everything. And basically the same structure in engineering. And then there are some other links, like Google Summer of Code and Outreach E-Docs, which are actually externally. So, that's how the website looks like. And now let's have a look at the Antora. So, that's the built engine that we're using to build the site. So, conceptually, it's very simple. We have the whole site, and it's made out of components. They call it components, and a component is basically a space in the docs with its own menu and a set of pages. So, we saw, for example, the comops page that was a component. Or we saw the Fedora 28 documentation that was a component. Even the QuickDocs are a component now. And this is basically all you need to know. There is one more level of complexity. And this is more these days, like everyone likes to call things modules. So, this is completely different than modules we have in Fedora. This is completely different than the modular way of writing documentation. This is just an Antora terminology. And basically it's a section of the component that can be split into a separate repo. For example, in the Fedora 28 user guides, for example, there are three books. And each of these is a separate git repo that can be owned by a different group, for example. But they get composed into the single space with the single menu. And when we build the site, and this is quite interesting, it builds, they call it virtual catalog of all pages. And that's this thing, which is version, component, module, and the page. Oh, by the way, I haven't mentioned that components can be versioned. So, let me show you. I forgot about that. So, if I have the Fedora 28 docs, for example, this is one version. And here in the upper corner, I can switch it to another version. Rohite F27. So, that's basically what the version is, component, module. And you can use this to either build the menu or to use internal links across the whole website. And this will get still the same, even though if you, for example, move the pages in the component a little bit, this will always work. And the build is from, it looks like this. We have many different git repos with the source, again, owned by different groups. For example, commopes modularity, quick docs, and there are the three guides. And we build it into a single documentation website. And in case you're curious, this is the link that gets you to the list and also to the build scripts. It's very easy to build. I'll show you that later as well, maybe. And by the way, I'll share the slides with you when I'm finished. All right. So, that was about Antora. And now let's have a look about contributing and how the source is actually organized. So, we are using git to store the sources. And we want to use similar workflows to software development. So, if you want to make change, you basically make your own copy, make the change, and then send a full request. And this is useful because someone else can make a review, make comments, and it makes basically a little bit less pressure on the contributor because they are not actually pushing the content themselves, but they have someone else reviewing it. So, that's always good. And this is the source structure in the Content repo. And I have built a template that is on this URL you can see. And basically, the most two interesting parts are these pages. And this is the navigation. This is the menu definition. But you also have images there and some metadata and things that support the build scripts. And this is, the root is one of the modules. Most pages have just one module because they're in one repo. And the default is called root, but you can have multiple ones, even like in one repo or spread to other repos. So, let's have a look at the template. And I'll mostly show you the menu definition, how it looks like. So, this is the repo. It's on pager, it's fedradocs slash template. And all the document, all the information is in the readme, so there's the structure. It describes what it is. I even have a recap of what component and module is because that might be confusing from the beginning. And one of the nice things about this is that you can build it very easily. All you need to have is a container runtime. So, for example, we are using Docker, and we have two scrapes, one for build and one for preview. And if you run it, it will just run the container in the background, build the website and start a local app server and it will just see the site. And you can do this with the individual repos. And you can also do the same thing with the whole website if you want to have a preview. So, I think this is one of the good steps here. And I promise you to see the navigation structure. So, if I go to files and I open modules, this is the default module, and I have this nav adoc. And these are the page IDs. And you might notice they are a little bit easier here. They don't have all the components in there because I'm referring to the same module to the same component. But I could use the full version if I liked. And it's basically just a list. The index ref, the name I want to see in the menu. And this is just basically a list that defines the structure of the website. So, if I build it, it looks like this, and these are the five pages. So, I have the index page. This is the nested thing, which is defined here. And that's how you basically can define the structure you want without moving the sources or changing the page ID. So, even if you want to reshuffle the menu completely, all the internal links will keep working. So, right now, if you want to make a contribution, and I'll talk about that in a minute, also, you need to go to this URL, which is our pager build repo. And there is a list of all the sources. And then you just go to the repo and make a contribution. But what we plan to do is an edit button. It will be on the right corner and just click that. It will get you to the git repo. And you can make an edit and just click a button and it will submit a PR for you. This needs to be done in Antora. It's supported for GitHub and to other gits. I don't think I remember. But if you host your sources on GitHub, it will work already. We need to make the change for pager upstream. All right. So, let's talk about the future. And there are a few things we want to work on. Automation is the big one. We want to have capability of building PRs for previews. So, if you submit a PR, you will see in the PR the whole site with your change. This is almost done. I think we have the pipeline setup. I still need to finish the image, but this should be weeks. We also want to build the whole site, which is right now manual process. But again, if we do any change, the CI will rebuild it and deploy it. And we've already won some tests. Still need to think about this. Translations. I've mentioned translations already. So, the URL is final. No changes in there. And we have some testing project in Zanada, which is the translation thing. And yes, we are making progress in there and it's definitely something we want to do very soon. It's one of the highest priorities. And QuickDocs. So, this is the thing we might need some help. So, as you could see, QuickDocs had the menu on the left with all the pages listed. And that was kind of crazy to navigate, right? So, we might want to do something with, I don't know, tags, search. So, if you're kind of person who can help us, that would be great. Probably, we want to build something like Stack Overflow or use something that exists that can provide this kind of experience. And search. So, good news is that the Antora documentation already has a search. So, we know it's possible. We just need to somehow integrate it with the Federal website and they will have search. And this should be even useful for the QuickDocs, I guess, as the first step. And we want more contributor docs. So, if you're a working group or a team in Fedora or SIG, you're very welcome to move your documentation in there. So, for example, I know Fedora infrastructure, Fedora relinch have their own documentation. It can be very easily moved there and you get your own space on the page. You can have it in your own repo, in your own place in the repo, your own rules for contributions, making changes that will just build it for you and publish, which I think would be useful. With it, for example, with the modularity project I also contribute to. And with this, I think that's all from my side. Are there any questions or concerns? Yeah. Would you like a mic? First of all, thank you for all your work with Antora. I know it was hard work. I was trying to test myself and my first question will be, we are moving from ASCII binder to Antora. How it affect the way we were working before for writing documents? Because the test is different, but I don't know if we need to, before we have to define the topic map, Jamel, and then to add the document inside the Jamel and the Jamel structure and then to write the proper ADOC file. So how is this new way different from that way? Yeah, that's a very good question. Thanks. So that's something I haven't mentioned. So before the dog book, between the dog book and the Antora, we had something in the middle that was called ASCII binder. And that's basically Brian Exabelt's work. So that was also great. And it was also using ASCII dog for the documentation, but to build it from multiple repos, it was kind of tricky. And also, when you define the page, you have to do one extra file that basically describes all the files in there and then define the menu. So right now, all you need to have is the page files and the NAV ADOC, which is the ADOC file with the list of links. And those links define all the structure and that's all you need, basically. And all the information is in the template, repo I showed. So that should be very clear. Otherwise, I'm very happy to help on IRC. Thank you. I have just another question, sorry. The other question is, because I want to port several SIGs websites to the documentation side, so how this will work? I mean, I should host it in the SIG pagure and how I reference it in the documentation pagure. Very good question. So you basically can host it in any Git repo you want. It can be pagure, it can be whatever. And you can put it anywhere in the repo you want again. You just need to have the structure with the structure of the template, sorry. And if you go to this URL, so this is the Fedora docs, and yeah, it's messy, but it's just a squeak here. And it's an easy URL. It gets you where you need to go. There's a main build script that lists all the repos with the sources. And in the files section, and I might even make it bigger for the projector, is this file called sci-taml. And if I open it, it lists all the Git repos we use as resources with all the branches in them. So that's how we reference the repos. So basically, you just let us know that you want this included in the PR if you like. I think opening an issue is fine. And all we need to have is like a clone URL that's publicly available, the name of your branch, and if you have that in a separate path. So for example, the comops have a directory slash docs. You can do anything you want. We can also specify it here, so that way it's not just interfering with your other code. So let's say I'm playing around with this and I wanted to do a preview build on my own laptop. Is Antora already available in Fedora, or how do I actually build on my own laptop? Very good question. So we don't have an Antora package in Fedora right now, but there is an upstream container image that has all the things you need. And we made it in a way that we have two scripts in the repo. One is called build and one is called preview. This is just like runs the container with the build site for you. First time it pulls the container from the upstream and then just like keeps working and this is just a container with a web server that makes you the preview. So that's basically all you need. It should be very easy and it works on Linux. I just did it on Mac. So that way we can attract contributors like using different... It should basically work anywhere where either the container runtime is or I think you can even install Antora so it's very flexible in this regard. Yeah. Okay, I have one question. If I'm not mistaken, the documentation is now locked in Xanata for translating. So when does this change? I think that would be best answered by Brian. Let me give him a mic. Everything I'm about to say is extremely ignorant, so correct me when I'm wrong. We locked the doc book versions of the documentation at the request of the internationalization and localization folks. We have test pushed projects into Xanata of the ASCII doc and quite honestly I just need somebody who uses Xanata to sit down with me and tell me if this looks right so that we can send an email out to the localization list saying go for it because after that I'd like to work with Adam to do a test publish on a language but I'm monolingual so I can't actually do it myself. Well, I have successfully translated British English to American English but beyond that I am monolingual and I have a credit, I can show you the web credit but like in all seriousness we need someone from the localization team who can look at what I've pushed into Xanata and say this is sane because I've never had to use Xanata and what I would like us to avoid if possible is giving the localization teams a bad set of pushes and projects to work with and then we're like oh well yeah those were all terrible so we're gonna throw all of your work away and ask you to do it again and that's kind of where we are with this. I would be really happy to sit down with you like immediately after this or during flock to get this worked out. I didn't do much translation work so I'm not sure if I'm the right person but I could look who is in your translation group and see who is in I don't know who is the admin of the group and... Let's just work out. Yeah, okay. One more thing just one enhancement for the page it will be good if the page has something to contribute or guide That's something we are working on and I think it should be coming in a few days right? I think there is a talk in flock about the user guy or the contributor guy so I'll say later Yeah, it wasn't underhand Yeah, it's different, sorry I just confused both But two things that should make you happy I did a Fedora classroom this Monday and it's recorded and it should land on YouTube on the Fedora channel and I just walked through the whole workflow of contributing so that's one option and another one is we are building a contribution guidelines or something like with all the steps and it'll land on the documentation page so it'll be just like self-explanatory but it's not very right and it's coming Any other questions? Yeah, we have one there So is the format actually Exkidoctor or Eskidoc? So the format is Eskidoc It's built by Eskidoctor which is somehow Extension above Eskidoctor actually it should be like Eskidoctor 2.0 so that's why I'm asking It's doctor Right, alright, so there is Eskidoctor, thank you I just want to make this clear that probably you should make it clear in the documentation and the second question is probably on Ryan, is Eskibinder dead or not? Would you like a mic? For those of you who don't know, Eskibinder is a project that was written by our good friends in OpenShift and it is used to build static sites for documentation as well from an Eskidoctor formatted set of repositories They designed it to solve some very specific problems around a single documentation set trying to build it for three different flavors of a software project It is not dead I do not know that it has much active contribution because it's currently solving all of the OpenShift requirements set It did not meet our requirements set and that is one of the reasons that we looked at Antora but that upstream as far as I know is in the same, I'll say maintenance phase tail end as it was before and inside of Fedora there, inside of Fedora we still are using it right now with the budget website because I haven't had a chance to convert that and we're still using it with no, that's it, just the budget website I'm asking because I package Eskibinder for Fedora so I'm asking what is the future of the package and if it will have some future and if it will need maintenance or not I direct you to Harrison on that one, in terms of its future and whether it will need maintenance I know that they're supposed to be looking at Antora for OpenShift but I don't know that they've had the resources to do it I don't expect you will be doing a lot of work in this package Okay, thanks Okay, thanks for all the questions if we have some more Yeah, so one additional so when Antora will be packaged in Fedora and what does it mean because looking at the Docker file and so on I don't know if they want to use it in Fedora So yeah, that's a very good question as long as we have someone who would like to package it for us so this is Node.js so we need someone with Node.js and CJR maybe is volunteering now so So I've started the process of trying to get all the dependencies for Antora packaged up in Fedora it's a non-trivial thing I think I've packaged 60 or 70 Node.js packages so far just to get the dependencies in so far and I don't seem to be making significant progress and getting anywhere close to the Antora package itself it's something I do in my spare time when I'm sitting on an airplane and have nothing better to do that sort of thing but it is going to be a long hard slog to get there unless we just bundle all the dependencies and that sort of thing But at least about the container as part of the CI I'm building a Fedora-based container that will use Fedora and Node.js package and then we'll just install the Antora from npm but otherwise it'll get just through our stuff that's the first step Any other questions? If no, thanks everyone for coming and enjoy your half an hour early lunch this is the only talk it does that