#337 2020 docs refactor [1/2]: Restructure for better discoverability of Council docs
Closed: no action needed a year ago by mattdm. Opened 2 years ago by jflory7.


Restructure council-docs to make it easier to understand how content is organized and where to find important project documentation


Many moons ago, in the long ago times of the 2018 Docs FAD, the Council was one of the first teams to get a documentation site launched with Antora. Hooray for being brave and trying out new things!

However, we know a lot more now about Antora than we did back then. The way we organized the council-docs repository is confusing. Instead of offering multiple modules grouped in one git repository, we group multiple independent docs sites together (council/, project/, even dashboard/) across multiple repositories. Some of them get bundled together in ways that are not obvious (council/ and project/ are in the same repo, but not dashboard/).

So this ticket is a proposal to stop the madness, take all the great things we have learned over the last two years with Antora, and set up the various Council-maintained Fedora Docs site in a more intuitive way.

Also, I am volunteering myself to work on this under the D&I umbrella. I think this work is valuable to making the more inner workings and big-picture focus of Council more visible to the wider community. Of course, I will need to pull in a few partners here and there to pull this off.


The work for this issue requires breaking URLs. :pensive: So, we need to be careful about this and leverage the (not obvious) way of setting up redirects in the Fedora Docs site builder.

Here is my list of tasks required to carry this out:

  1. Move all Council-maintained documentation to a single git repo (one repo or two could be debated)
  2. Unify all Council-owned documentation under docs.fp.o/lang/project/ URL namespace
    • e.g. docs.fp.o/lang/project/council/, docs.fp.o/lang/project/dashboard/, docs.fp.o/lang/project/objectives/
  3. Set up redirects for the broken URL namespaces to new one.
  4. Write documentation about the documentation. Examples:
    1. Which docs are where
    2. Where to submit patches for which docs
    3. Better experience for testing and building local copies of docs

The above task list is to kickstart the conversation. Comments and feedback on how to implement this welcome.


  • Important project and Council source docs are easier to discover by the average contributor or user
  • Get the Council docs sprawl under control before it starts to hurt

I like the idea generally. The dashboard was intentionally separated because the people who contribute to that are not necessarily Council members and I wanted people to be able to push directly. That said, there's no reason we couldn't consolidate it and have non-Council members contribute via pull request. In practice, the non-Council members either don't provide updates or they feed them through me anyway.

My term on the Council is coming to an end at the end of this release cycle. I am dropping my assignation as I don't have capacity to carry this out in the remainder of my term.

A thought to leave for the future, but this might be a good ticket to bundle into a potential Fedora Docs hackfest or meet-up. We could bundle the Council docs work into a time/place where we have more Docs folks together, since that knowledge and expertise will be important to carrying out this work successfully.

Metadata Update from @jflory7:
- Assignee reset
- Issue marked as blocking: #338
- Issue priority set to: Needs Review (was: Next Meeting)

2 years ago

Project and council are already in the same repo. And we dropped the dashboard, and haven't created a separate objectives space (#338). So I think we should just close this. I did propose something similar on the docs list which includes putting various team docs closer together... let's continue that conversation there.

Metadata Update from @mattdm:
- Issue close_status updated to: no action needed
- Issue status updated to: Closed (was: Open)

a year ago

Login to comment on this ticket.