 So up next we have Peter Boy. He's going to talk about Fedora docs plans for the future or how you can contribute We're just doing a little bit of text that up here for his laptop Okay, that's someone has a Fedora sticker at hand so I can hide No, oh it's already online. I need my manuscript. Sorry. Yeah, well, I'm Peter Boy. You can read And it's the first It's the first time I'm in an in-person Fedora meeting so probably some some words about me I'm Working as a scientist at the University of Bremen. No redhead. No Whatever I graduated in sociology as a first and as a minor in applied mathematics That was the home of computer science those days and statistics and Right because of that my colleagues thought it was a perfect person to care about our department's computer equipment And it grew and grew because we were funded as an excellence Research collective so we had our own equipment. We had freedom from the university IT and The side job grew and grew too but at the end I ended with a 24 or so servers and hardware At the end all of them in Fedora server and Well And I began to contribute to Fedora to things to Matthew's reboot of the server of a game. I wanted to Spend some of our internal Fedora documentation to Fedora That's what the starting point Nowadays I do a lot of more Then come to putting docks and when Ben a year ago started to the reboot the docks team Which was dormant for many years at that time. I Came to the crazy idea to join the docks team as well and Well, now I'm the member of the board and the only one who is regularly available Okay, so it could be better, but Let's start what's in its Some pages didn't work with the equipment here and other pages. Okay, so Wonderful the IT technology and Well, let's start with a Short analyzes where we are where we stand the way we are standing It's not a secret the state of the docks in Fedora There's a lot to wish for let's say is that way We are suffering in with the docks team for many years Until recently we had on nine our docks From Fedora 18 onwards or so and if you skip through the docks release by release you could see from release to release a number of documents which compose the docks but less and Sometimes any times ended with just to it was a installation guide and it was the Administration guide Well, but as a scientist I tried to make analyzes the idea was the issue is another Coincidence that we have such a How to put it not a bad state but a state which has many open wishes It must be a structural Issue and the here's is we have a weak integration of docks into the Fedora project and into the Fedora development There are several signs of it Is it here? Okay. Oh You may see and compare some starting points of several distributions It is Fedora. It is rocky Linux and arc Linux or how they are pronounced And maybe You notice a difference between them, but we don't want to make a guessing display here if you compare them you see these quite successful Distributions have all a document link in the main part of the website Besides you don't it does we have no document link and all website It's a weak indicator what indicator If docks is not in the main objective of Fedora of the Fedorians and if you have a look at our procedures eGV have a lot of Regularities a lot of decision chains to make a Package all these decision change handle about technical technical issues There is no requirement to have a dock At least at me it for instance and the description field for the package that there's a link to any kind of description and Or even worse we have additions We have a lot of regular of a lot of procedures to have it to make it with this edition It's a product document requirement You have to specify the marketing chances that you have to specify the user base a problem But you don't have to have a documentation We have no issues to distribute our flagship our lighthouse Distributables without documentation available fortunately Most of our additions have a documentation But that I think it's more by coincidence than by system system medical Issues But the problem is This this week integration. I think you can It's a long-standing water indicate we can change that and foresee the future and as far as I know Matthew can Talk about it documentation was no topic in the current next to do a discussion I suppose Yeah, yeah, so Next-chance is 20 30 or so flash probably I think we had documentation as one of the Points somewhere and then it ended up falling out in one of the reorganizations But there's kind of a bucket of here are the things we didn't know what to do with where should they go That's gonna be part of the need that conversation, but yeah, you're right. It's not been a focus except there is one section like the accessibility documentation has a Call out where that's kind of about The documentation we have already rather than making it a specific focus All right, oh I have to hurry This State of our documentation has some I suppose not fortunate for effects of our distribution as a whole For instance, we are hiding all our excellent technical capabilities because without documentation nobody sees it and many Fidorian want to For instance set up a web server. They don't find and documentation and start with documentation From Debian or whatever they are finding and wondering because why it doesn't work And the thing is okay Fedora doesn't work or Fedora is Rated as difficult to use and some decide them to switch to another Distribution that's a negative effect In the wrong run among others We could I think we could fix it without too much work The minimum could be to change our Package package guides to include some kind of documentation. It's new for packages. Oh, no, it isn't you We are used to do that with change proposals It's I had to read double time or three. But yes, we have in our change proposal the section about documentation and to Explain our users what to do. So our packages are not So unused to documentation. Maybe in the long run we have a chance to To improve the situation Well, that's a general consequences we have Well, that's the thing The the gist of it. We hide all our excellent engineering results because we have no documentation no one find found finds it Well, and we have An effect of our documentation tools themselves we switched sometimes they go from Doc book and Be the poor publican was it to eski doc and and Torra And a good workflow and the problem is that is a workflow that is fine for developers But not fine for those here who are dedicated writers You I don't know from any public publisher who asked for a good repository or ask for us guitar. That's the different workflows and The workflow has a lot to desire because for instance at the moment We have no with Preview tool so you are writing docs without having as see your the presentation of the content and Unfortunately, if you are writing docs There's interdependence between the content and the presentation of the content and so our tools are missing very important Element of writing Well, and we have a kind of quandary at the moment We have a workflow which is perfect for developers and we are Urgent need of developers who write documentation Or we have the right people who want to write documentation and Have a huge barrier in form of the bit and workflow with The public best workflow, which is quite only well unknown to them and this is a really a problem after Ben started the reboot of the Of the Docs group We managed to get eight new contributors over the one year Well currently the age the eight one is a zero again So yeah, after one year nearly at the same point as he started a year ago with events initiative. I Don't know the exact reasons but involved in all cases more issues with the workflow and with the drip User interface Which isn't nice and powerful but 80% of this unneeded for documentation and we have no Options at the moment as I got to know to do simplify for docs So we have a new we have one barrier Dropped and haven't built a new one No, nevertheless We can not rate until we have a better integration. We might have to do some things in the time we have So We started or I started to evaluate how we can improve documentation with the circumstances as they are and where we Took three Yes, the two ways the one way is to fix document structure The most most problem is in the door our document structure was it was perfect for Fedora 10 but all The changes we made with the last Fedora next to to create the additions didn't Well, didn't went to the documentation We had in so we had the unified installation guy which Should be valid for all our for all our distributables, but it wasn't So Sorry, this is Well, we change the doc's home page and I wrote a block post About the change we made and we adopted the structure of our documentation the structure of our Distribution and Well, we had to be resolved some documentation problem with that the responsibilities for the edit for the additions is now the addition workgroup and The addition workgroup should be familiar with the workflow and pull request workflow. So it seems it's not a problem for them I hope so to make the proper Right to create the proper documentation Um, if I better Okay, that's this foot Coming with Fedora release 27. We changed the home page We're in the Moment you can see a bit more we have we have a Just an introductionary power first part at the top and in the center of the page are our additions or additions to be in case of In a keynote and silver blue it is and We have we have an opportunity to add some of our goodies G's quick talk is for example or a specific Box for the arm for the arm computers for aspects for a single board computers, which is currently Discussed topic. Well, there are both some I skip that. Sorry This is the other way was to improve to make contribution easier for our users and And the way that was first step was as documentation team were documented the procedure So we created documentation about how to contribute to Fedora and Concentrated on quick docs Because this type of content Which is not so complex and not so huge as Contribution F installation guide for addition and so it's easier for users to start to contribute to and Where we developed it is this documentation how to do it we Developed some templates for creating a quick doc document and Various others Under others Helpful material, so we hope it is easier to do that. I Skip all the the details at the moment We are trying to Demonstrate these things in our workshop sessions on Friday, I suppose somewhere so we can demonstrate the things in detail and we can Hopefully get feedback if we didn't have good documentation or a bad one for instance But another step is we have to improve our doc tools Specifically we need a text processing option for Asking doc documentation with a preview or a viscic interface The only one I found at the moment is ask you ask you don't FX. Yes, and Well, we need to develop us to develop our Documentation tools and that's a long-term goal. It's not for the next to Fedora additions or so but what we already have in the Work is to automate our the generation of our release nodes so these notes suffer from the same issue as our user documentation from release to release the percentage of changes which were included in the release notes are going down and to Help therefore we are going to automate that Probably not with the next but with over next. Okay. That's a short overview with some technical issues and Yeah But we have time for questions. I think it's not me at G Hi So you mentioned there are some I suppose Issues with people onboarding in terms of like learning to get workflow and that kind of thing Do you think there's an issue with the documentation format? So ask you doc over something like markdown, which is a bit more ubiquitous. No, not us not ask doc It's it's a tool issue a tool on the workflow issue workflow issue All of these where it is a it was you aware users without a relevant development experience But some of them were dedicated writers. That's problem was not to make a text the problem was to get the text in the in our documentation and it was additional work for them. That's a problem and It was not attractive enough. I'm not I'm too for city was the German wording. I think we can fix that but it's additional work on our side or my side Well, just a little comment on the workflow So I've been involved in publishing lately and the process that people use like the professional writers in air quotes Without good. It's a living hell to be fair And I believe that spreading the git based workflow is actually a net good for everyone For non-developy writers as well because the process Can spread around and they can bring it to with them to other projects Maybe my problem problem is the guys are away I would like to have it and all of them struggled with the workflow And the additional work That's And well my goal of man and at the moment is to make it easier for them to provide better guidance For instance you plan we are planning Virtual shared writing sessions for us. We have someone attend during the session who can fix problems or explain them, but we have additional work to do Okay, so I have no problem with the git word for I do that myself and our projects. It's not a problem, but The non-development defined users are not they are not the problem, but they have the problem so Well, it may be a bit of a shameless plug, but in virus our distro So when we switched from media wicket to sphinx and git The community of the commutation developers actually exploded so sometimes I wonder if it may be Just an issue of marketing that workflow to people or attracting the right kind of people yeah, I Think well if I if I come read what they have written they were the right people content-wise at least and And Well, it's I'm quite Unhappy what is it they said to have lost them. It's They weren't able to write Qualitative high-level documentation Do you think it might be worthwhile to I like having you consolidated in one tool But do you think it might be worthwhile to move something like the quick docs to another system like a dedicated wiki or even to Solving all my problems with discourse using the discourse as a doc's plug-in that was marked down based if it would it Might it make sense to have a different like easy format docs that people could use Or would you it's better to? There are some people who propose to go back to wiki. I don't think it's it's a solution You should have unified system for normal docs and quick docs. You have to refer back and forth It's a matter of presentation to the public I think it's not a good idea the the counter example is the arm area they have and they are only on wiki and it's hard to find them because It doesn't fit into our documentation structure. And so my My what is the quicker in German? It's a help my helping stick Make a box for the arm on the on the on the wiki on our main page. So to have a topic which is highly discussed at the moment Well, you have to offer something about it. And so I'm more on the trip Make it easier to use a workflow and I'm hoping on the consulate council that we get a better integration and so long run so and I hope that our Repository, I don't know a pig. You are Pagoo. I don't know how to pronounce However you want okay That we keep can keep that because it's much easier with the workflow because it's much less powerful Okay, but all but we use what I give need for documentation is there. So It's a meant hopefully you can use it for some years for for what it's worth. I Jolene who is a lawyer Red Hat who is awesome, but you not a not a coder not She's not She's not non-technical, but she's like she's like she's a lawyer, right? And She found it. So I convinced her that she should you know use our docs process for the new fedora legal page she didn't want to use the wiki and She found Pagor too hard to use but I was happy with sick with get lab Once you figured it out. She thought it was much much easier. So that's my one other data point there I think also if we had a dedicated get lab We could configure some of it to turn all of that stuff off so we can have a much simpler like at least a section That's much simpler But you know that's we have to figure out how to get to something like that I'm sorry. I'm throwing stream of conscious thoughts that you hear but There's also there's a stalled thing in get lab where they are looking at having an ASCII doc preview in addition to the markdown Preview which would probably help, but that doesn't seem to be going anywhere But maybe that's something we could invest in working on as I don't Java program ASCII actually ASCII doc affixes it they have some working the editing To it and the manual like any text processing things and they have a preview and you can plug in your own CSS. So with some Effort we couldn't we can use it for our own CSS It'd be nice to have that edit like into the get Forge tool entirely. So I don't know maybe if you people do end up investing more in Pagor development We could solve both of those problems and maybe maybe make it have that preview Well, never the less before we are go I'm still on the trip to make documentation in Fedora better and to try hard to get it done. So Although I'm some time sometimes I'm a bit desperate about I have to see the night and then it's okay Thank you very much and just Yeah