18:30:25 #startmeeting docs 18:30:25 Meeting started Wed Feb 16 18:30:25 2022 UTC. 18:30:25 This meeting is logged and archived in a public location. 18:30:25 The chair is bcotton. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 18:30:25 Useful Commands: #action #agreed #halp #info #idea #link #topic. 18:30:25 The meeting name has been set to 'docs' 18:30:33 #topic Hellos and introductions 18:30:42 Hello hello hello! Who's here? 18:30:50 .hello 18:30:50 pboy: (hello ) -- Alias for "hellomynameis $1". 18:30:55 .hi 18:30:56 darknao: darknao 'Francois Andrieu' 18:31:00 .hello mroche 18:31:02 mroche: mroche 'Michael Rochefort' 18:31:09 .hello copperi 18:31:10 copperi[m]: copperi 'Jan Kuparinen' 18:31:11 .hello cgranell 18:31:13 cgranell[m]: cgranell 'Camila Granella' 18:31:26 .hello pboy 18:31:27 pboy: pboy 'Peter Boy' 18:32:06 .hello pbokoc 18:32:07 pbokoc: pbokoc 'None' 18:33:13 .hello shaunm 18:33:14 shaunm[m]: shaunm 'Shaun McCance' 18:34:02 alrighty, we have a good group here. let's get started! 18:34:08 #topic Why are we here? 18:34:35 #info This is a weekly meeting for contributors to Fedora and CentOS documentation 18:34:45 #link https://discussion.fedoraproject.org/t/fedora-and-centos-docs-revitalization/36353/ 18:35:38 #info The intent of this meeting is to have a time for coordination and collaboration. We want to have most decisions happen asynchronously 18:36:10 #info It also helps show potential contributors that we are an active, organized group, and gives them a place to come introduce themselves 18:37:19 As a bit of historical context, I lead the Fedora Docs team in the early part of the previous decade. A lot has changed since then, so most of how that worked probably doesn't apply now 18:37:41 So it's up to us to figure out how we want this team to work in 2022 :-) 18:38:24 #topic Upcoming work 18:38:25 so! 18:38:56 there are a ton of things we can work on and only so many of us to go around. so i thought we'd spend some time coming up with some specific focus areas 18:39:06 people can, of course, contribute wherever they want 18:39:38 but sometimes people don't know where to start. and if we have a collective effort in a few areas, we can make meaningful progress 18:39:57 this benefits the projects broadly, but it's also good for us psychologically :-) 18:40:19 so let's spend some time discussing some ideas 18:41:19 yes, let's :) 18:41:53 well, okay, we're going to need a redesign of the homepage because it keeps gaining new items/bubbles and it's turning into a mess 18:41:56 anyone have some ideas? 18:41:59 my always step one: is there a content plan? 18:42:00 maybe a good starting point could be reviewing the fedora dics oage: https://docs.fedoraproject.org/en-US/fedora-docs/ ? 18:42:10 docs page* 18:42:24 s/dics/docs/, s/oage/page/ 18:42:44 #info idea: redesign of home page (pboy) 18:43:06 Yes, Biggest problem: our home page and the documentation Installation Guide and Adminstrators Guide. 18:43:13 It is more a structural problem than a content problem. 18:43:21 #info idea: reviewing https://docs.fedoraproject.org/en-US/fedora-docs/ (cgranell) 18:43:25 And actually easy to fix. 18:43:41 We also need to get rid of the old pre-Antora docs so they stop showing up in search engines, but I don't want to lose them completely; Matt suggested a while back that they're still on Internet Archive, which is fair, but we could also just grab all the published PDFs, put them into a tar or something, and keep that around, I'd like that better than relying on an external service 18:44:03 pboy: i agree. We've grown the docs site organically and it shows. it needs some gardening 18:44:09 shouldn't it be https://docs.fedoraproject.org/en-US/docs/ ? 18:44:20 we can use a robots.txt file to get search engines to ignore them 18:44:49 #info Getting rid of the old pre-Antora docs (pbokoc) 18:44:59 bcotton: Yes, that's the way things are going. No offense meant! 18:45:26 #link https://discussion.fedoraproject.org/t/hey-docs-team-i-need-a-volunteer-to-drive-the-removal-of-old-docs/35946 18:45:31 Related to getting rid of pre-Antora docs, it would be nice if older docs (current release -2 basically) were clearly marked with a banner on top. Someone (darknao I think) has already been working on that 18:45:32 pboy none taken :-) 18:45:59 darknao++ for lots of recent UI improvements 18:45:59 bcotton: Karma for darknao changed to 4 (for the current release cycle): https://badges.fedoraproject.org/tags/cookie/any 18:46:02 I am a friend of checking what is still usable before discarding and then migrating. 18:46:22 Leave no work unused. 18:47:00 pboy++ 18:47:00 bcotton: Karma for pboy changed to 3 (for the current release cycle): https://badges.fedoraproject.org/tags/cookie/any 18:47:03 There's also an ongoing effort to move to Antora 3.0; there are already plenty of PRs open for some repos, e.g. here: https://pagure.io/fedora-docs/release-notes/pull-request/785# but we'll have to cherry-pick these changes to every published branch in the relnotes/install guide/sysadmin guide. I'll handle that though 18:47:21 pbokoc: yep, that's in progress, and actually, I would need someone to merge this PR to get this going: https://pagure.io/fedora-docs/release-docs-home/pull-request/15 18:47:48 darknao, ok, done :) 18:47:56 (about the version banner) 18:47:59 cool thanks :) 18:48:23 #action pbokoc to cherry-pick antora 3.0 changes in relnotes/install guide/sysadmin guide 18:48:39 about Antora 3.0, the prod&stg environment are both using it already 18:49:00 there is still one repo that's not working, but not sure if it's maintened anymore 18:49:00 #info idea: move to GitLab (ryanlerch) 18:49:07 (let me find the link) 18:49:22 https://pagure.io/fedora-docs/taiga-docs/pull-request/1 18:49:28 I have a similar patch waiting in a PR for the CentOS Contributor's Guide 18:50:16 mroche, yeah you have 2 PRs there now, don't you. I'll get to them soon :) 18:50:49 Thanks pbokoc! 18:51:19 Hm, Besides the important and urgent individual issues: We should not forget (or miss) to develop a medium-term overall plan! 18:51:19 darknao yeah, we've bascially shut down teams.fp.o, so that whole repo is not particularly useful now 18:52:00 bcotton: ok so maybe we can remove it completly from docs.fp-o? 18:52:30 darknao: i think so, unless someone makes a compelling argument that we should keep it 18:53:00 yeah let's get rid of it (I'm saying that as the one who wrote the thing :) 18:53:09 alright, I'll handle that part then. 18:53:19 Speaking of medium-term stuff: anaconda's GUI is still using sources for like F25's Install Guide for the built-in help, and someone needs to figure out how to allow it to use current sources 18:53:50 pboy: that's a good point. shaunm and I have a goal of getting the team active and self-sustaining again, but not a plan for what happens when that's achieved. that's a good thing to work out collectively 18:54:18 #info idea: Get anaconda to stop using F25 install guide sources for built-in help (pbokoc) 18:55:07 another idea in mid-long term: implement a CI pipeline for docs :D 18:55:19 That's going to require collaboration with the anaconda people; suggested contacts are mkolman and vslavik 18:55:44 to check links for instance, i've seen there is a lot of broken links in the current docs 18:55:50 Oh yeah, definitely darknao. I have no idea about how the last year's attempt ended up 18:56:28 Currently, we have this https://pagure.io/fedora-docs/fedora-docs-ci 18:56:48 which was never completely implemented 18:56:51 broken links seem like an easy thing for a robot to find in CI 18:57:02 and automatically archive old release docs could be part of CI 18:58:05 but I plan to dig into that at some point in the futur, and move that part to openshift or something 18:58:21 #info Docs CI (darknao) 18:58:22 maybe we can use Gitlab-CI now that we have an instance here 18:58:41 that'd be a good argument for moving to GitLab :-) 18:59:04 Another goal would probably be to switch all default branches to main, someone was asking about that recently-ish 18:59:18 +1 for that 18:59:23 and it's quite easy to do 18:59:37 #info Switch all default branches to main (pbokoc) 18:59:50 And also release notes for F36 will become relevant soon 19:00:36 Well, without wanting to be negative: Before we build CI, we should have something to distribute? 19:00:50 I ran into issues making PRs in pagure for centos that I'm pretty sure were due to an incomplete transition to using main. 19:01:24 Not saying not to do it. Just saying I think there are gotchas that are sometimes overlooked, and we shouldn't overlook them. 19:02:54 pboy, we do have something to distribute - the docs :) Our plan for CI was to run tests on PRs, provide live previews, and rebuild the site on request (when a commit is merged into a published branch) instead of the current way of hourly rebuilds 19:03:32 pbokoc +1 19:03:49 that make me think of another work idea: rework (or simplify) the docs build pipeline 19:03:58 ...or the centos way of pbokoc runs the build on his machine, hehehe 19:04:17 #info idea: simplify the docs build pipeline (darknao) 19:05:04 i think we have a good collection of what to work on for now, so let's spend the rest of the time talking about how we work 19:05:10 #topic Team operation 19:05:15 pbokoc: Yes, consent. Perhaps a bit exaggerated. I just do not want to lose focus on content, new updated content. 19:05:29 so specifically, i'm thinking of things like how we make decisions and how we track work 19:05:43 shameless plug: for those interrested, I'm supposed to talk about how the docs build pipeline actually work at the Infrastructure meeting tomorrow 19:06:47 #info darknao will talk about the build pipeline at the Fedora Infrastructure meeting tomorrow at 1600 UTC in #fedora-meeting-1 19:07:21 I think it is #meeting-3:fedoraproject.org 19:07:54 so i don't think we want to be too strict or formal. we want to make sure people feel empowered to make decisions but that we're giving people a chance to offer their input 19:07:57 yeah, it's in fedora-meeting-3 19:08:05 #undo 19:08:05 Removing item from minutes: INFO by bcotton at 19:06:47 : darknao will talk about the build pipeline at the Fedora Infrastructure meeting tomorrow at 1600 UTC in #fedora-meeting-1 19:08:43 I have some ideas that i'll put in a Discussion thread 19:08:44 Along the lines of that question, Ben, how would people like to track work between Fedora and CentOS considering they don't share repos/git instance/issue trackers? 19:09:11 #action bcotton to post ideas for decision-making to a Discussion thread 19:09:46 mroche: that's a great question. even just for fedora, there are many repos to track issues, etc 19:09:58 Or even discussions. Fedora docs discussions are now on Fedora's Discourse, CentOS continues using mailing lists. It's going to be hard to bring people together. 19:10:52 I also prefer mailing lists, by the way. :-) 19:11:04 one approach would be to have one meta repo just for work tracking (and basically use it for project-type work and not bug fixes) 19:11:54 pbokoc: another good question. i'm inclined to ask CentOS to move Docs from the mailing list to discussion.fp.o, ideally if we could make the #docs tag work in both the Fedora and CentOS categories 19:12:23 but i'm not fully sold on the idea, and would be open to other suggestions 19:12:26 (i know what mattdm would say) 19:13:04 regarding tracking... I don't suppose there's a way to get a "view" in gitlab that would include issues from multiple repos, is there? That would be best I think 19:13:10 The CentOS community in general is more hesitant than Fedora about ditching mailing lists. 19:13:30 pbokoc: I think you can if all those repos are in the same sub group 19:14:59 I think some adjustment on the CentOS side is also needed. I never followed the -docs mailing list, but when I went to check it (which is how I found out about this meeting) it seemed pretty much a place for the git bot to post results, rather than seeing a lot of active discussions. Then again CentOS Wiki work hasn't been a big thing in a while. 19:15:47 darknao, that would probably be the best. Alternatively, we could disable issues on all repos and include a "report a bug" link in each page's header next to the "Edit this page" one and direct people there. The problem with that is that I bet a ton of people wouldn't realize they have to manually specify what exactly they're talking about, but that could probably be helped if gitlab allows customizing the issues page e.g. through pre-filled text 19:15:47 in the description box 19:15:47 s/work/content addition+edits/ 19:16:15 pbokoc: see this sub group for instance: https://gitlab.com/groups/fedora/websites-apps/-/issues 19:16:21 the reason is - I want to preserve the Edit this page link because it takes you directly to whatever the source of the current page is, which is really useful 19:16:49 pbokoc: agreed re: "Edit this page" 19:17:26 of course, this means we'd need a common name space for centos and fedora, which is..not how things are set up currently 19:17:41 darknao, yeah, that looks good 19:18:02 alternatively, we come up with another plan or abandon the idea of being a unified team :-) 19:19:07 I think that teams between Fedora and CentOS may need to be separate, but that doesn't mean there's no overlap in content/pipeline that can't be taken advantage of. 19:19:25 anyone want to take an #action to look at our GitLab options and report back to the team? 19:19:56 I mean, right now, it's pretty rare to get any contributions to CentOS docs from outside of Red Hat, mroche is an exception to the rule. And also, Red Hat's CCS has been interested in sharing RHEL docs sources with CentOS, the big issue is how to do that because they use a completely different build system and converting back and forth is going to be a nightmare 19:20:03 i do think a unified team working across two namespaces isn't the worst thing that could happen. a lot of contributors will only contribute to one project or the other in practice 19:20:43 * mroche is a hatter, just not a CentOS/RHEL/Fedora eng 🙂 19:20:54 oh :-D ok then 19:22:31 Yeah, I was thinking from the perspective of operations between the two groups, they seem fairly different and with what you mentioned from CCS's interest, the main area of CentOS docs I see would be the contributor's guide. But again, I'm still new to the docs space so I don't have a holistic view of this. 19:22:48 Those docs are in a public repo, btw, but not yet hooked up to any publishing pipeline: https://gitlab.com/redhat/centos-stream/docs/enterprise-docs 19:23:01 At least some of them. I haven't cross-checked the list recently. 19:23:50 yeah, I know, but antora won't take them, it requires a completely different structure, CCS have their own homebrewed system 19:24:16 Another consideration for CentOS docs are the docs that come out of SIGs. 19:24:30 Oh, good point. 19:24:53 Docs site: https://sigs.centos.org 19:27:27 so we're almost out of time. i'll repeat my call for someone to look at our GitLab options (in cooperate with Red Hat's CPE team, probably) and come back to the team with some ideas 19:27:41 anyone willing to take that? 19:28:56 Is Fedora self-hosting GitLab or using gitlab.com? 19:29:04 using gitlab.com 19:30:31 I'd be happy to facilitate communication with CPE, just would need someone more technical or with more experience in docs with me 19:31:46 okay, our hour is up. there's still a lot more to figure out, but we had a good meeting today 19:31:52 thanks everyone for coming! 19:32:02 i'll see you around chat/discussion/mailing list :-) 19:32:06 #endmeeting