#337 2020 docs refactor [1/2]: Restructure for better discoverability of Council docs
Opened 10 months ago by jflory7. Modified 6 months ago

Summary

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

Background

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.

Details

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.

Outcome

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

6 months ago

Login to comment on this ticket.

Metadata