docs/tickets
20
4
Issues 32 Pull requests Projects Activity

Pilot "Fedora Docs Captain" role in three pilot groups #50

New issue
Open
opened 2026-06-25 15:37:33 +00:00 by jflory7 · 10 comments
jflory7 commented 2026-06-25 15:37:33 +00:00
Owner
Copy link

Summary

Create a "Fedora Docs Captain" role handbook for anyone who wants to be the lead for Fedora Docs in their team, and work with three pilot teams to test the role handbook.

Background

For a while now and also at Flock 2026, we spent time discussing the idea of a Fedora Docs Captain, or someone who is an active team member of another team, WG, or SIG but is willing to be the Fedora Docs "lead" for that group. This is one way we can empower the various teams that make up the decentralized web which we call Fedora to write amazing docs. The challenge we are trying to solve here is the perception that the Fedora Docs Team is responsible for every single page of content in docs.fp.o, which is not true.

To make this work possible, we should work with some pilot teams who are willing to help us figure out what this role looks like. It will take some initial scoping by the Fedora Docs Team, and then once we have a "spec" for the role, we can work with potential captains to put this plan into action.

Details

We need to spend more time discussing, as a Fedora Docs Team, what a captain should and should not do. For example, a Docs captain for a specific SIG need to be involved in all of the Docs Team work? Maybe not. Should they have regular check-ins with other Docs Team captains? Perhaps. This is where we need creativity, ideas, and realistic perspectives on what we can do to make the communication better.

For the pilots, @pboy and @pbokoc reached out to a few people during Flock, and we likely have three candidates for a pilot:

Each of these three teams would have different focuses:

  • Fedora Kernel: Migrate the existing Quick Docs section, Kernel and booting, to a dedicated Docs site. Redirect Quick Docs pages to their new home with Antora page aliases.
  • Fedora Multimedia: Categorize multimedia content in the Quick Docs site. Come up with a new content hierarchy for multimedia content in a dedicated Fedora Docs site. Migrate the Quick Docs multimedia content to a dedicated multimedia docs site. Redirect Quick Docs pages to their new home with Antora page aliases.
  • Fedora AI/ML SIG: Migrate the existing Quick Docs pages into the Fedora AI/ML SIG docs site. Migrate the existing SIG documentation on the Fedora Wiki to Fedora Docs. Redirect Quick Docs pages to their new home with Antora page aliases. Create a documentation culture among the SIG.

Outcome

More decentralized leadership of specific components of Fedora Docs, and a model framework for how someone can be a leader for Fedora Docs in their team, Working Group, or SIG

# Summary Create a "Fedora Docs Captain" role handbook for anyone who wants to be the lead for Fedora Docs in their team, and work with three pilot teams to test the role handbook. # Background For a while now and also at Flock 2026, we spent time discussing the idea of a _Fedora Docs Captain_, or someone who is an active team member of another team, WG, or SIG but is willing to be the Fedora Docs "lead" for that group. This is one way we can empower the various teams that make up the decentralized web which we call Fedora to write amazing docs. The challenge we are trying to solve here is the perception that the Fedora Docs Team is responsible for every single page of content in docs.fp.o, which is not true. To make this work possible, we should work with some pilot teams who are willing to help us figure out what this role looks like. It will take some initial scoping by the Fedora Docs Team, and then once we have a "spec" for the role, we can work with potential captains to put this plan into action. # Details We need to spend more time discussing, as a Fedora Docs Team, what a captain should and should not do. For example, a Docs captain for a specific SIG need to be involved in all of the Docs Team work? Maybe not. Should they have regular check-ins with other Docs Team captains? Perhaps. This is where we need creativity, ideas, and realistic perspectives on what we can do to make the communication better. For the pilots, @pboy and @pbokoc reached out to a few people during Flock, and we likely have three candidates for a pilot: - Fedora Kernel: @jforbes - Fedora Multimedia: @rathann - Fedora AI/ML SIG: @jflory7 Each of these three teams would have different focuses: - **Fedora Kernel**: Migrate the existing Quick Docs section, _Kernel and booting_, to a dedicated Docs site. Redirect Quick Docs pages to their new home with Antora page aliases. - **Fedora Multimedia**: Categorize multimedia content in the Quick Docs site. Come up with a new content hierarchy for multimedia content in a dedicated Fedora Docs site. Migrate the Quick Docs multimedia content to a dedicated multimedia docs site. Redirect Quick Docs pages to their new home with Antora page aliases. - **Fedora AI/ML SIG**: Migrate the existing Quick Docs pages into the Fedora AI/ML SIG docs site. Migrate the existing SIG documentation on the Fedora Wiki to Fedora Docs. Redirect Quick Docs pages to their new home with Antora page aliases. Create a documentation culture among the SIG. # Outcome More decentralized leadership of specific components of Fedora Docs, and a model framework for how someone can be a leader for Fedora Docs in their team, Working Group, or SIG
jflory7 self-assigned this 2026-06-25 15:37:33 +00:00
pboy commented 2026-06-26 02:30:33 +00:00
Owner
Copy link

Maybe this ticket better fits into the Quick Docs repo tickets. It is part of Quick Docs improvement Project.

Maybe this ticket better fits into the Quick Docs repo tickets. It is part of Quick Docs improvement Project.
pbokoc commented 2026-06-26 20:13:11 +00:00
Owner
Copy link

No, I think this is a Docs-wide thing, we should keep it here.

No, I think this is a Docs-wide thing, we should keep it here.
robinsheps commented 2026-06-30 14:05:19 +00:00
Copy link

@jflory7 as per my comment in the meeting. I am happy to help liaise with other teams. Obviously being completely new to this I will need to make contact with the relevant groups but I am happy to do so. I may need a bit of guidance as to what you are actually looking for to start with but I am happy to pick it up and learn

@jflory7 as per my comment in the meeting. I am happy to help liaise with other teams. Obviously being completely new to this I will need to make contact with the relevant groups but I am happy to do so. I may need a bit of guidance as to what you are actually looking for to start with but I am happy to pick it up and learn
jflory7 commented 2026-06-30 17:41:58 +00:00
Author
Owner
Copy link

Discussed in 2026-06-30 Fedora Docs Team meeting.

I presented the "Docs Captain" pilot concept to the team. The role envisions Docs Team members serving as documentation liaisons to other Fedora SIGs, helping ensure Quick Docs content stays current through structured ownership. Three initial pilot targets were identified from Flock discussions:

  • Kernel/booting (@jforbes) — e.g., Kernel Overview section in Quick Docs
  • Multimedia (@rathann) — content currently scattered across Quick Docs
  • AI/ML SIG (me) — e.g., Ollama section in Quick Docs

@goroboro expressed interest for the future but needs more experience first. @robinsheps volunteered to help liaise with the kernel/booting and multimedia teams, and will be the primary contact for anyone interested in getting involved with this pilot.

Kicking off coordination

I'd like to use this ticket to begin organizing the pilot with @robinsheps, @jforbes, and @rathann. A few items to get us started:

  1. Migration timeline: We should discuss a target deadline for when we want to deprecate the relevant Quick Docs content and migrate it to a new or existing Fedora Docs site. What timeline feels realistic for each area?
  2. Support for pilot captains: @jforbes, @rathann — do you need help with your respective docs areas (kernel/booting, multimedia)? We want to make sure you have the support you need, whether that's writing help, review capacity, or anything else.
  3. Matrix coordination: @robinsheps, it would be helpful for you to join the Matrix rooms for these teams to start building connections. #devel:fedoraproject.org may be the most appropriate starting point for kernel and multimedia discussions.

Action items

  • @robinsheps: Drop a comment on this ticket expressing interest in the liaison role ✅
  • @robinsheps: Begin coordinating with me, @jforbes, and @rathann to organize the liaison effort
  • @robinsheps: Join the appropriate Matrix rooms (start with #devel:fedoraproject.org) and connect with the relevant teams
  • @jforbes, @rathann: Please share any questions about how this pilot will work, and let us know if you'd like support with your docs areas
  • I will define the pilot role concept and success metrics before onboarding new volunteers
  • HELP WANTED: Additional volunteers to serve as Docs Captains for other Fedora SIGs — contact @robinsheps for help on getting involved
  • IDEA (@goroboro): "I definitely think better documentation about ownership and points of contact would help a lot"

Assisted-by: Claude Opus 4.6 (1M context)

_Discussed in [2026-06-30 Fedora Docs Team meeting](https://discussion.fedoraproject.org/t/fedora-docs-team-meeting-2026-06-30/195195/3)._ --- I presented the "Docs Captain" pilot concept to the team. The role envisions Docs Team members serving as documentation liaisons to other Fedora SIGs, helping ensure Quick Docs content stays current through structured ownership. Three initial pilot targets were identified from Flock discussions: - **Kernel/booting** (@jforbes) — e.g., [Kernel Overview](https://docs.fedoraproject.org/en-US/quick-docs/kernel-overview/) section in Quick Docs - **Multimedia** (@rathann) — content currently scattered across Quick Docs - **AI/ML SIG** (me) — e.g., [Ollama](https://docs.fedoraproject.org/en-US/quick-docs/ollama/) section in Quick Docs @goroboro expressed interest for the future but needs more experience first. @robinsheps volunteered to help liaise with the kernel/booting and multimedia teams, and will be the primary contact for anyone interested in getting involved with this pilot. ### Kicking off coordination I'd like to use this ticket to begin organizing the pilot with @robinsheps, @jforbes, and @rathann. A few items to get us started: 1. **Migration timeline:** We should discuss a target deadline for when we want to deprecate the relevant Quick Docs content and migrate it to a new or existing Fedora Docs site. What timeline feels realistic for each area? 2. **Support for pilot captains:** @jforbes, @rathann — do you need help with your respective docs areas (kernel/booting, multimedia)? We want to make sure you have the support you need, whether that's writing help, review capacity, or anything else. 3. **Matrix coordination:** @robinsheps, it would be helpful for you to join the Matrix rooms for these teams to start building connections. `#devel:fedoraproject.org` may be the most appropriate starting point for kernel and multimedia discussions. ### Action items - ~~@robinsheps: Drop a comment on this ticket expressing interest in the liaison role~~ ✅ - @robinsheps: Begin coordinating with me, @jforbes, and @rathann to organize the liaison effort - @robinsheps: Join the appropriate Matrix rooms (start with `#devel:fedoraproject.org`) and connect with the relevant teams - @jforbes, @rathann: Please share any questions about how this pilot will work, and let us know if you'd like support with your docs areas - I will define the pilot role concept and success metrics before onboarding new volunteers - **HELP WANTED:** Additional volunteers to serve as Docs Captains for other Fedora SIGs — contact @robinsheps for help on getting involved - **IDEA** (@goroboro): "I definitely think better documentation about ownership and points of contact would help a lot" <sub>_Assisted-by: Claude Opus 4.6 (1M context)_</sub>
pboy commented 2026-07-01 07:50:32 +00:00
Owner
Copy link

The original plan was to set up a sort of sub-group for a specific area, such as the kernel, consisting of an 'engineer' and an 'author'.

The purpose is to

  • avoid placing an additional burden on the 'engineer' with the details of accurate, high-quality documentation
  • spare the 'author' from having to conduct extensive research into technical details with the risk of potentially misunderstanding them

So we need at least 2 persons who are jointly mentoring the subject (kind of godparenthood).

And this point currently applies specifically to Quick Docs (with a future extension to ‘Fed Docs’). The edition-specific documentation already includes both an 'engineer' and, in principle, an 'author'.

The task here is more about initiating or strengthening communication between the Working Group and the Docs team in order to achieve consistency in the documentation style.

The original plan was to set up a sort of sub-group for a specific area, such as the kernel, consisting of an '_engineer_' and an '_author_'. The purpose is to - avoid placing an additional burden on the '_engineer_' with the details of accurate, high-quality documentation - spare the '_author_' from having to conduct extensive research into technical details with the risk of potentially misunderstanding them So we need at least 2 persons who are jointly _mentoring_ the subject (kind of godparenthood). And this point currently applies specifically to Quick Docs (with a future extension to ‘Fed Docs’). The edition-specific documentation already includes both an 'engineer' and, in principle, an 'author'. The task here is more about initiating or strengthening communication between the Working Group and the Docs team in order to achieve consistency in the documentation style.
qvest commented 2026-07-07 18:39:47 +00:00
Copy link

Hello, I would like to help with Fedora Multimedia, but I am not sure where to start. I mentioned in the Fedora Documentation Matrix room that RPM Fusion-related docs were all over the place. I would like to start helping that on aspect

Hello, I would like to help with Fedora Multimedia, but I am not sure where to start. I mentioned in the Fedora Documentation Matrix room that RPM Fusion-related docs were all over the place. I would like to start helping that on aspect
jflory7 commented 2026-07-08 03:25:32 +00:00
Author
Owner
Copy link

@pboy I really like your idea of pairing people up. Someone from the Fedora Docs Team, and a subject-matter expert in each team. I hypothesize 1-1 guidance being more effective here.

Hey there @qvest! Thanks for following up and commenting here. I think Multimedia might be the most ready content we could start working on. It also has some of the biggest work behind getting it organized and cleaned up from Quick Docs.

I am imagining what a team of three structure might look like, for each of the three topics (AI/ML, Multimedia, Kernel):

  1. WG/SIG Lead: A subject-matter expert from the Working Group / SIG who can verify information, provide advice on what is relevant or not to publish, and generally verify the authenticity of our docs with the current state of Fedora Linux.
  2. Fedora Docs Team Sponsor: This should be a more experienced member of the Fedora Docs Team, who can participate and guide the collaboration. This role would be helpful for building uniformity in our style guide and improving consistency across Fedora Docs sites.
  3. Fedora Docs Team Lead: This person is a key role and driver of the entire collaboration. This person helps structure the written content, review old content, create new hierarchies of organization for content, and helps oversee the execution of improving that WG/SIG's docs, together with the Lead and the Sponsor.

I see this creating a 3-way accountability. Then, we could start to match people up into pods.

I wonder what others think here? 🤔 Am I over-complicated it?

@pboy I really like your idea of pairing people up. Someone from the Fedora Docs Team, and a subject-matter expert in each team. I hypothesize 1-1 guidance being more effective here. Hey there @qvest! Thanks for following up and commenting here. I think Multimedia might be the most ready content we could start working on. It also has some of the biggest work behind getting it organized and cleaned up from Quick Docs. I am imagining what a team of three structure might look like, for each of the three topics (AI/ML, Multimedia, Kernel): 1. **WG/SIG Lead**: A subject-matter expert from the Working Group / SIG who can verify information, provide advice on what is relevant or not to publish, and generally verify the authenticity of our docs with the current state of Fedora Linux. 2. **Fedora Docs Team Sponsor**: This should be a more experienced member of the Fedora Docs Team, who can participate and guide the collaboration. This role would be helpful for building uniformity in our style guide and improving consistency across Fedora Docs sites. 3. **Fedora Docs Team Lead**: This person is a key role and driver of the entire collaboration. This person helps structure the written content, review old content, create new hierarchies of organization for content, and helps oversee the execution of improving that WG/SIG's docs, together with the Lead and the Sponsor. I see this creating a 3-way accountability. Then, we could start to match people up into pods. I wonder what others think here? 🤔 Am I over-complicated it?
jflory7 commented 2026-07-08 13:16:28 +00:00
Author
Owner
Copy link

@robinsheps Would you be interested in working on Fedora Kernel/Booting docs? Is this something you would enjoy working on?

@robinsheps Would you be interested in working on Fedora Kernel/Booting docs? Is this something you would enjoy working on?
goroboro commented 2026-07-14 13:41:13 +00:00
Copy link

Happy to be a sponsor on Fedora Kernel and Booting docs. I will pick up doc tasks and issues and work through sections as required.

Happy to be a sponsor on Fedora Kernel and Booting docs. I will pick up doc tasks and issues and work through sections as required.
❤️ 1
jflory7 commented 2026-07-14 14:15:43 +00:00
Author
Owner
Copy link

Discussed in 2026-07-14 Fedora Docs Team meeting.

I presented a proposal for three complementary roles in each pilot team: a WG/SIG Lead (subject-matter expert who verifies information), a Fedora Docs Team Sponsor (experienced docs member who guides consistency and style), and a Fedora Docs Team Lead (key driver who structures content and oversees execution). @pboy suggested that matching a team lead with someone experienced in technical writing and/or Fedora Docs would make the pilot work best, which I agree with. @pbokoc noted that the sponsor and lead workload will be heavier upfront while SIG leads learn the docs workflow, but should taper off over time. The team discussed timeboxing the pilot to the F45 release (2026-10-20) to evaluate whether to scale up or conclude the experiment. @goroboro expressed interest in helping with kernel/boot docs, and @qvest was mentioned as interested in multimedia.

Follow-up:

  • Everyone: Review the roles proposal (WG/SIG Lead, Sponsor, Team Lead) and provide feedback on this ticket
  • @pbokoc: Follow up with @robinsheps on docs lead role for kernel/booting
  • Each pilot team (Kernel/Booting, Multimedia, AI/ML SIG) could use additional volunteers — comment here to express interest
  • Pilot evaluation deadline: F45 release (2026-10-20)

Assisted-by: Claude Opus 4.6 (1M context)

_Discussed in [2026-07-14 Fedora Docs Team meeting](https://discussion.fedoraproject.org/t/fedora-docs-team-meeting-2026-07-14/196628)._ --- I presented a proposal for three complementary roles in each pilot team: a **WG/SIG Lead** (subject-matter expert who verifies information), a **Fedora Docs Team Sponsor** (experienced docs member who guides consistency and style), and a **Fedora Docs Team Lead** (key driver who structures content and oversees execution). @pboy suggested that matching a team lead with someone experienced in technical writing and/or Fedora Docs would make the pilot work best, which I agree with. @pbokoc noted that the sponsor and lead workload will be heavier upfront while SIG leads learn the docs workflow, but should taper off over time. The team discussed timeboxing the pilot to the F45 release (2026-10-20) to evaluate whether to scale up or conclude the experiment. @goroboro expressed interest in helping with kernel/boot docs, and @qvest was mentioned as interested in multimedia. **Follow-up:** - Everyone: Review the roles proposal (WG/SIG Lead, Sponsor, Team Lead) and provide feedback on this ticket - @pbokoc: Follow up with @robinsheps on docs lead role for kernel/booting - Each pilot team (Kernel/Booting, Multimedia, AI/ML SIG) could use additional volunteers — comment here to express interest - Pilot evaluation deadline: F45 release (2026-10-20) <sub>_Assisted-by: Claude Opus 4.6 (1M context)_</sub>
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
Contributors' Guidance
Improve written Material
 Improve the existing contributor documentation

  
Contributors' Guidance
technical support measures
 Improve contributors' guidance by technical efforts like vale or similiar linters

  
effort
high
 Will take a long time

  
effort
low
 Easy fix

  
effort
medium
 Will take some time

  
good first issue
Take this if you're new!

  
help wanted
Needs help or feedback from the wider Fedora community

  
meeting topic
Need to discuss this at a Docs team meeting

  
needs changes
Needs changes or fixes before closing

  
needs reporter feedback
Additional feedback or information from the reporter is needed to advance

  
needs review
Someone needs to look at this

  
priority
high
 Fix this NOW NOW NOW!

  
priority
low
 Low priority tasks

  
priority
medium
 Medium priority tasks

  
priority
on hold
 Work has been temporarily halted, usually because another task needs to be completed first.

  
type/content
Changes to the contents of the site - the actual docs

  
type/misc
Changes to non-content parts of the site. CSS, Actions, scripts, etc.

No labels
Contributors' Guidance
Improve written Material
Contributors' Guidance
technical support measures
effort
high
effort
low
effort
medium
good first issue
help wanted
meeting topic
needs changes
needs reporter feedback
needs review
priority
high
priority
low
priority
medium
priority
on hold
type/content
type/misc
Milestone
Clear milestone
No items
Projects
Clear projects
No items
No project
Docs Team Meeting Planner
Assignees
Clear assignees
No assignees
jflory7
jforbes
rathann
robinsheps
6 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
docs/tickets#50
No description provided.