19:30:28 #startmeeting docs 19:30:28 Meeting started Wed Nov 22 19:30:28 2023 UTC. 19:30:28 This meeting is logged and archived in a public location. 19:30:28 The chair is pboy. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 19:30:28 Useful Commands: #action #agreed #halp #info #idea #link #topic. 19:30:28 The meeting name has been set to 'docs' 19:30:40 The object today is to provide an opportunity to discuss some current issues directly, quasi virtually vis-a-vis 19:31:15 We planned to hold this on Matrix, but unfortunately we couldn't prepare this in time. 19:31:29 So we propose we stay here for now. 19:31:49 Let's see who is here 19:31:59 #topic Roll call 19:32:12 Please, everybody who is lurking, say either ".hello2" or ".hello " 19:34:42 .hello2 19:34:43 pbokoc: pbokoc 'None' 19:34:56 Welcome! 19:35:10 Hi pboy, how's it going? 19:35:33 I'm fine, thanks. Although a bit overcommitted. 19:35:40 .hello klavier 19:35:41 hkl: klavier 'Test Lab' 19:35:47 Glad to see you again. 19:36:01 Let's start with the Agenda 19:36:03 hi all, I have too step out in 20 minutes today. 19:36:36 hkl Welcome. that's Ok for me. 19:36:50 I'm a bit short in time, too. 19:36:59 #topic Agenda 19:37:11 #info Repo Information 19:37:11 #info Release Notes 19:37:11 #info Online Workshop 19:37:11 #info Podcast about Docs 19:37:11 #info Open Tickets 19:37:11 #info Open floor 19:37:27 #topic 0. Repo Information 19:37:37 Just as a short info: 19:37:49 I had a chat with Aoife Moloney, our Program OP about the Repo Fedora Accounts Documentation 19:38:05 We kind of inherited that repo 19:38:16 but none of us does anything know about it. 19:38:26 And s accumulates issues 19:38:56 Aoife has taken into her hands to find an appropriate maintainer for it. 19:39:20 And probably to move the repo elsewhere. 19:39:36 Any comment about this? 19:39:47 I'm not sure we need to move it 19:40:21 The original author is Ryan Lerch, he's not really active in Fedora docs anymore, but he's part of Red Hat's CPE team (Fedora releng, infra, etc. - among other things) 19:40:33 Yeah, but maybe the new maintainer wants to have it in their working space 19:40:53 Right, sure, if someone wants to maintain it and move it elsewhere then why not 19:41:26 pbokoc Yes, Ryan told me shortly after he moved the repo to us, that he unfortunately no longer can work on it. 19:41:43 Right, okay then 19:41:56 There are only 2 open issues right now, I think I could take a look at them 19:42:15 And overall there are only 5 total (3 closed), so it's not like it gets tons of reports 19:42:24 pbokoc That would be fine! 19:42:46 And also one of the open issues seems to be empty, like someone opened it by accident :) 19:43:15 Anyway, I'll talk to Aoife and tell her I'll look after the repo 19:43:21 I'll need to talk to her soon anyway 19:43:52 Yeah, not so many at the moment. But I don't like it to have an unmaintained repo and without any idea how to resolve it :-) 19:44:05 Sure, that's understandable 19:44:09 Maybe a kind of tick by me. 19:44:16 OK, next topic. 19:44:25 #topic 1. Release Notes 19:44:43 This is maybe the most important of todays topic. 19:44:58 e have to decide, how to proceed with F40. 19:45:12 Yeah so, I actually wanted to talk about this too :) 19:45:14 And maybe make a plan, how to cooperate on this. 19:45:40 According to my information so far. 19:46:02 The current first run didn't do as well as we hped. 19:46:32 The problem is: not enough information in the change proposal section Release notes. 19:47:03 pbokoc can you add or correct? 19:47:14 You mean the script? Yeah, until we get a LLM to scan change proposal pages and turn them into something readable, a script isn't going to help 19:47:38 What is LLM (sorry, not im my internal translator) 19:48:31 Large Language Model - the thing everyone in the media is calling AI. Think ChatGPT and similar :) 19:48:55 Anyway, there are no plans to actually use anything like that, it's just a quip from me 19:49:03 Oh, that' a big step. 19:49:11 OL. relieved :-) 19:49:39 Basically, that's what it would take to really automate Release Notes. So we're stuck writing them by hand. 19:49:46 But I do have some plans for F40. 19:50:01 OK. go on! 19:50:37 1) I'm going to move the repo to gitlab and update it (change master branch to main, replace the old builder script with the current one, update the structure, etc.). Now's the best time to do it - early after a release, before a bunch of new Changes are opened. 19:50:50 You know, since I'll have to migrate current open issues by hand :) 19:51:49 2) I'll flatten the structure. Currently the relnotes are separated into three main sections (Desktop/Developers/Sysadmins), and each has a bunch of subsections on separate pages. That's a holdout from the past, when putting a ton of content on a single page made the whole thing hard to read. 19:52:25 Now that we have those autogenerated floating tables of contents on the right thanks to darknao, navigation is way simpler and having long pages isn't a problem. 19:52:57 This is also going to solve the issue where some pages are sparse or empty while others are very long. 19:53:39 I'll keep the developer/desktop/sysadmin separation, but that's it. So the whole relnotes for each version will be about 4 separate pages (these three + the intro section). 19:54:04 I'm hoping to get this done by the end of the week unless anyone has any objections or comments. 19:55:10 No objection, but maybe an addition. We could need a Server section for Server, CorOS, IoT and Cloud. 19:55:37 It will be shorter than destop, I think 19:55:50 But hopefully not empty 19:56:11 Or does this fall into sysadmin? 19:56:18 Hmm, changes that impact server experience historically go under Sysadmin. 19:56:53 OK. let's try the sysadmin section for them 19:57:08 We could also rename Sysadmin to Server and Desktop to Workstation to keep the naming consistent with Fedora editions :) 19:57:39 Yeah, consistency is a good idea, I thnk 19:58:29 Anyway, there's also a deeper issue with how we write release notes in general. Other than the installer section, historically we've been using the Change process to identify what needs to be covered. Which is reasonable, but it's a bit incomplete. 19:59:46 An initial idea was, to get a complete list and to retrievethe title and description in the Change Proposal for that. 20:00:01 But you didn't use those this time, I suppose? 20:00:58 I mean the script didn't retrieve them 20:01:28 Well, I almost never use them (the title, yeah, but not the description), because they're written for Fedora contributors and FESCO - they're primarily there to explain why the change is useful to Fedora and how it'll impact the distro. It's a different target audience, the relnotes exist to inform end users what changed. 20:01:43 They're also usually written in... less than ideal English :) 20:02:32 But pragmatically perhaps better than nothing 20:03:10 The script pulls contents of the Release Notes section, which is often empty. We could easily change that, but still. Here's a good example of what I'm talking about: https://fedoraproject.org/wiki/Changes/F39MingwEnvToolchainUpdate 20:03:55 That's just not very useful documentation. Other times, it goes into very minute details that aren't useful either. 20:04:49 Perhaps we can give the change owners a few tips for the summary. 20:04:50 Often the description also talks about what *will* be needed in order to make the change work, which is irrelevant to us, because by the time the relnotes come out, these things have already happened and the target audience doesn't need to know. 20:04:59 Hahah we've tried that before :) 20:05:37 Hm, hope dies last :-) 20:05:47 Here's an example of the change page going into details that aren't very useful for release notes: https://fedoraproject.org/wiki/Changes/AllowRemovalOfTzdata#Detailed_Description 20:05:53 And again, better than nothing. 20:06:24 Oh yeah and often the relevant info is scattered across multiple sections - Description, Detailed description, Scope, Upgrade/comp impact... 20:07:08 And maybe, in discussing the proposals we can nag the owners to give more useful info. 20:08:04 We can use plenty of that info but it always needs a writer's attention - and that's the time and effort consuming part, the script can only help with creating an initial structure and copy-pasting sections that may or may not be relevant. And also a script can't decide whether a certain Change should go under Sysadmin or Developer. 20:08:23 At least, I'm looking at each proposal whether it is relevant for server. 20:09:11 Yeah agreed. 20:09:43 But wouldn't if be a start? 20:09:59 I mean to take the title and the summary 20:10:19 And to inform the owner in the proposal form how it is used. 20:10:26 Well, it can't hurt 20:11:03 I think flattening the structure will help a bit with this too. Because with the old structure, let's say I'm documenting this: https://fedoraproject.org/wiki/Changes/F39MingwEnvToolchainUpdate#Release_Notes 20:11:04 We will never achieve 100%m but even 50% would be progress (at least I hope) 20:12:37 The Release Notes section is one sentence. If it ends up being on a separate page with no other relnotes in that section, it just looks ridiculous. But if we stop using subpages and only do 3-4 pages of content, then it's practically guaranteed that there will be other stuff there too, so it won't look too bad and I won't feel bad for using single sentence relnotes :-) 20:13:20 yes, Agreed. that resolves one bit issue. 20:13:34 The other issue is completeness 20:13:48 And in your example: 20:13:49 Really my issue with the script is that it doesn't even achieve 50%, more like 0,5%. Because it can't assign changes to their sections, which means I still have to take the script's output and copy-paste each relnote to where it belongs. But while I'm doing that, I might as well just copy from the wiki directly. 20:14:33 Ok. But doesn't the owner has to give the proper category? 20:14:49 We discussed that with FESCO a year ago. 20:15:25 Well, setting up categories on the wiki would help with that... as long as people used them properly, which I'm not too confident about :) 20:15:40 Everyone should be able to decide between the 3 caegories 20:16:15 I see, you have a lot experiences. I'm still a bit more optimistic :-) 20:16:27 Hehe 20:16:47 Yeah, asking for categorization between only 3 categories might be doable. 20:16:55 And do we have an alternative? 20:17:30 The alternative is we keep doing it manually 20:18:04 We can't expect you to do that. Not in the long term. 20:18:15 That'a too a dull work. 20:18:59 And the same applies to everyone else. 20:19:36 The time is nearly up. 20:19:47 How should we proceed? 20:20:10 Okay, let's take this on the forums then. I'll write up my current plans and what we talked about just now, and we'll discuss how to proceed from there. 20:20:46 OK! Let's start a discussion now and hopefully be better prepared. 20:21:20 Alright. 20:21:50 OK. I switch directly to Open Floor, just in case .... 20:22:01 topic 5. Open floor 20:22:11 Anything toi discuss here? 20:22:16 Sorry 20:22:27 #topic 5. Open floor 20:22:39 Anything to discuss here? 20:22:44 I don't have anything else. 20:23:30 Well, I see nobody else, so I'll close in a short time 20:23:32 5 20:23:42 4 20:23:53 3 20:24:06 2 20:24:16 1 20:24:24 #endmeeting