Sorry to revive this but I only just read the thread and feel the need to correct the record here.
On Thu, Jul 2, 2026 at 11:47 AM Neal Gompa <[email protected]> wrote: > On Thu, Jul 2, 2026 at 7:31 AM Iñaki Ucar <[email protected]> wrote: > > > > > > On Wed, 1 Jul 2026 at 12:14, Neal Gompa <[email protected]> wrote: > >> > >> > >> I also can't see it being a good idea to make it more difficult for > >> contributors, either. To be honest, I'd rather just keep the wiki and > >> maybe invest in an extension to support Markdown in the Fedora wiki. > >> The backlinking and historical data is incredibly valuable. > > > > > > There are many things (i.e. the docs) that were moved to the forge. > Changes are just another form of documentation, so I don't see how moving > this to a forge could make things more difficult. You can argue many > things, but you can't argue that "git" is gonna somehow turn contributors > away from the change process. Especially when most (all?) change owners > already use git in some capacity (because they are packagers, or contribute > to the docs, or maintain some software ustream, or...). > > > > I could argue it, as we did lose contributors to the docs with the > transition to Antora. People absolutely struggle to contribute to our > docs now. We made the change to align with RHEL in the hopes they'd > contribute to our documentation, but that didn't happen either. > No, sorry, that's not how it went. For the last couple of years before the switch to Antora (which was in 2018), most of the Fedora docs contributors were old guard RHEL tech writers - that is, paid Red Hat employees - doing the work in their spare time, and most documentation was rebranded RHEL docs. There were plenty of community contributors before, of course - some of them are even still active in Fedora today - but they ended up leaving docs for various reasons, and new ones weren't showing up. Eventually the couple of RH writers started leaving too as they switched jobs, and eventually I was basically the only one left. I didn't have the time or energy to do much more than slap together some release notes once every 6 months and update the site with an incremented version number, so all the other docs were just republished without updates. It was getting pretty bad. The main issue was the old markup language (DocBook, which is an XML dialect), which was an insurmountable barrier to entry for any new community contributors. It's difficult to find people willing to deal with XML without being paid, and any potential new contributors took one look at the sources and I never heard from them again. And Fedora did use DocBook because of Red Hat, it's what RH used. In 2018, both Red Hat and Fedora docs switched to ASCIIDoc, which is significantly simpler and more readable, and therefore less terrifying to new contributors. But the switch wasn't really coordinated between the two, and each did it for a different reason: Red Hat wanted to modularize their docs, which you can't do with DocBook, and Fedora desperately needed something that doesn't send contributors screaming upon first contact. At the same time, ASCIIDoc was an up and coming new markup language aimed specifically at technical documentation and even "marketed" itself as DocBook replacement, with direct comparisons on the website and everything, and it was suitable for both use cases, so both Fedora and Red Hat's Content Services ended up picking it. There was some talk about sharing RHEL docs with Fedora (and CentOS), but it never went far for various reasons. Red Hat also used a custom build system (Pantheon), while Fedora uses Antora. As for contributors struggling: ASCIIDoc still isn't super simple once you go beyond writing a single page, but it's so much better it's not even funny. More importantly, the main barrier to entry for most docs people isn't ASCIIDoc but git - and the only way for us to fix that would be moving all docs to the wiki (or Discourse - yes, it's been suggested), which isn't gonna happen. ASCIIDoc and Antora didn't magically bring the Fedora Docs community back, it took a long while and a lot of effort, but right now we do actually have an active community of recurring contributors and even mentors, largely thanks to the initiative we've been running since last November: https://fedoraproject.org/wiki/Initiatives/Fedora_Docs_2025. (Please keep in mind that this is strictly a reply to Neil's claim, I'm not expressing any opinions on whether Changes should stay on the wiki or go into a git repo, that's a wholly separate issue and I'm fine either way. Although, while I'm at it - you guys really should start paying attention to the Release Notes section... but that's a separate conversation we'll all have later :P) > > Contributing to a wiki is significantly easier than contributing to a > git controlled document that requires a separate rendering process. > > Now, as for Fedora Changes? That is a different story. That said, the > main beef people seem to have with Changes is that they are written in > wikitext rather than markdown. I rather like the real-time editing and > drafting capability our wiki gives, it's particularly great for > collaborating with others on a jointly submitted document. But yes, > I'd prefer a markup I use more frequently than wikitext. > > > > > -- > 真実はいつも一つ！/ Always, there's only one truth! > -- > _______________________________________________ > devel mailing list -- [email protected] > To unsubscribe send an email to [email protected] > Fedora Code of Conduct: > https://docs.fedoraproject.org/en-US/project/code-of-conduct/ > List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines > List Archives: > https://lists.fedoraproject.org/archives/list/[email protected] > Do not reply to spam, report it: > https://forge.fedoraproject.org/infra/tickets/issues/new >
-- _______________________________________________ devel mailing list -- [email protected] To unsubscribe send an email to [email protected] Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/[email protected] Do not reply to spam, report it: https://forge.fedoraproject.org/infra/tickets/issues/new
