Ever since we switched the Fedora Docs portal at Fedora Documentation :: Fedora 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.
First off, we need that search field. Whatever structure we come up with, unless we have a search field, things will get buried.
Second, I’d go with the approach you mentioned up above as first item: documentation should be divided by use cases. If I go to a documentation site, I don’t want to be bombarded by idioms created by that product/community, I want them explained and I want to know how to get x done.
Here’s a quick sketch as a basis for discussion, note that I’m not saying this should be the structure, but it’s a starting point.
each tab has its contents specific for its category, server would have instructions on installing a LAMP stack or whatever’s popular nowadays, traditional server, CoreOS. General would have information about SIGs and more pointers, about the Fedora project itself, etc
What do you think of this structure as a basis and going into what points each category would have?
(Disclosure: I’m new to this community and I’m deeply* familiar with python Sphinx and readthedocs.org)
I don’t know if these topics have already been discussed, but I can share some of the following “lessons learned” from previous projects:
Are there analogous sites in the community that would serve as a model? By analogous, I mean multi-layer, multi-dimensional, multi-purpose? (eg. https://www.python.org/ ).
The search function is really critical, so are the analytics (bad URL’s, referrer pages, churn, etc)
Intersphinx (I don’t know the generic name) which allows you to resolve links to remote sites
* Deeply in the sense that I have implemented a private instance of readthedocs and included LaTeX support (but not search)
