Ever since we switched the Fedora Docs portal at https://docs.fedoraproject.org/en-US/docs/ to Antora, we’ve seen an influx of all kinds of docs that people asked us to host. We have Fedora user guides, project documentation, contributor documentation, all sorts of stuff. That’s great, but we need to figure out a better structure because right now it’s becoming increasingly difficult to find anything that isn’t linked from the front page.
Off the top of my head I can see two approaches that we could take:
Line up several categories of documentation by use case: again, off the top of my head, that would be at least user docs (“how do I do X?”), project docs (“what’s the Council or FPC? What SIGs do we have? What’s FLOCK?”), and contributor docs (“how do I contribute to docs? How do I add a package? How do I submit a patch? What are the packaging guidelines?”). This would be really helpful, but it would take a lot of effort, and people from various projects would have to work with multiple repositories and make sure they’re contributing to the right one when adding new content.
More verbose info about each category on the front page. For example, the Mindshare Teams category’s “subtitle” right now isn’t very helpful to someone who doesn’t know what Mindshare is; instead we should list all subcategories we have under Mindshare right on the front page, so people unfamiliar with the project don’t have to click through half the site before they find what they need.
The two aren’t totally mutually exclusive, but the first point is going to take much more effort.
Also a search field would be pretty helpful, even if it’s just a link to DDG that adds “site:docs.fedoraproject.org” to the search term - but even if we get that we should still try to make content easier to find without it too.
What do you think?