We need to talk about the doc site structure

fedora-documentation

#1

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?


#2

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.

Written explanation for accessibility:

  • huge search bar on top
  • 4 (?) tabs saying Desktop, Server, General, FAQ
  • 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?


#3

(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)


#4

Based on looking at the current landing page, I think the top level index could be arranged from the general to the specific; like this:

About Fedora

About Fedora: Community

About Fedora: Community: Diversity & Inclusion

  • Outreach
  • Google SOC

About Fedora: Community: Governance

  • Council
  • Budget

About Fedora: Teams

About Fedora: Teams: Eng

  • Eng Teams
  • SIGs

About Fedora: Teams: Mindshare

  • Mindshare
  • CommOps
  • Ambassadors

About Fedora: Packaging Guidelines

Products

(call them collections, projects, highlights, anything except packages or repositories)

  • Rawhide
  • SilverBlue

Docs

Docs: Quick Docs

  • (howtos, useful resources, etc not specific to a version)

Docs: User & Admin guides by release

The following (popup) menu items (specific for each version):

  • Rawhide (bleeding)
  • Fedora 29 (current)
  • Fedora 28 (stable)
  • Fedora 27 (legacy)
  • Fedora 26 (security patches only)
  • Fedora 25 (eol)

Docs: Fedora 29 (current)

… Describes why you might want to use this particular release and then include links to:

  • Fedora 29 Release Notes
  • Fedora 29 Installation Guide
  • Fedora 29 System Administrator’s Guide

Disclaimer: not drawn to scale. Object may appear farther away than they are. Not for children without adult supervision…