docs/tickets
20
4
Issues 32 Pull requests Projects Activity

UI/UX enhancements for knowledgebase-style pages in Fedora Docs Antora theme #51

New issue
Open
opened 2026-06-26 00:28:08 +00:00 by jflory7 · 3 comments
jflory7 commented 2026-06-26 00:28:08 +00:00
Owner
Copy link

Summary

Research and implement visual changes to the Fedora Docs Antora theme to better support knowledgebase-style content with complex hierarchies of information.

Background

Migrated from commops/tickets#71, where significant research and community discussion took place. This is part of the Fedora Docs 2025 Initiative.

The current Fedora Docs theme excels at presenting book-like, linear documentation but is less optimized for content structured as a knowledgebase — short-form answers to questions, deeply nested topic hierarchies, and cross-referenced content. Several CommOps docs pages (e.g., contributor best practices, team profiles) would benefit from a different page structure.

Research and Discussion Completed

Significant groundwork has been done by Chris Idoko (@chris), @pboy, @pbokoc, @ryanlerch, and Justin Wheeler (@jflory7):

  • Antora/AsciiDoc research: Chris Idoko explored pass-through blocks, UI bundle customization, and how .adoc files integrate with custom HTML/CSS/JS. He found the system is "almost identical to markdown" and identified two paths: AsciiDoc pass-through blocks or UI bundle customization.
  • Interview playbook: Chris Idoko drafted an interview playbook (reproduced below) for gathering structured feedback from documentation maintainers and contributors on the feasibility and direction of UI customizations.
  • Docs Team feedback: @pboy clarified that the proposal is about page structure (knowledgebase layout vs. book layout), not content changes, and noted that "a lot of preliminary work has already been done." @ryanlerch provided technical insights on the Antora theming system.
  • Alternative ideas explored: A complementary onboarding website ("My Fedora First Steps") was discussed as a curated entry point, separate from but linking into the main docs.
  • CommOps meeting follow-up (2025-09-30): @jflory7 was to reach out to @pboy and Chris Idoko to determine next steps. @pboy confirmed the ticket should move to the Docs team tracker.

Interview Playbook

The following interview playbook was drafted by Chris Idoko to guide structured feedback gathering from documentation stakeholders:

Topic: Implement UI/UX enhancements for a knowledgebase to Fedora Docs Antora theme
Owner: Chris Idoko (FAS @chris)

I. Purpose

  • Objective: Gather feedback from documentation maintainers, contributors, and interested team members on customizing the Fedora Docs site UI bundle to support custom HTML, CSS, and JavaScript. The current documentation infrastructure — based on Antora and AsciiDoc — follows a book-like format, which, while informative, does not offer the best experience for user interaction.
  • Audience: Interviewers (internal team members, volunteers, Docs teams, etc.)

II. Project Goals

  1. Enhance the Documentation UI — Implement customized UI pages within key sections of the documentation site to improve UI layout and user engagement beyond the default Antora theme.
  2. Improve Contributor Experience and Onboarding — Provide clear, visually guided, and interactive content that simplifies understanding of the documentation structure, where to contribute, teams to join, and how to get started.
  3. Grow the Contributor Base — Make it easier for newcomers to identify where and how to contribute through better information navigation, clearly marked contribution entry points, and a more intuitive knowledge base.

III. Questions & Considerations

  1. Feasibility and Sustainability

    • If this UI customization initiative is adopted, how feasible is it to maintain over time?
    • What level of effort would be required to support, update, and document the custom UI components long-term?

  2. Best Practices and Technical Guidance

    • What best practices should we follow when integrating custom HTML, CSS, and JavaScript into the Fedora Docs site?
    • Are there known limitations or constraints within the Antora theming system that we should be aware of?

  3. Documentation and Development Environment

    • Is there existing documentation for the Antora theme development environment?
    • Are there any guidelines, conventions, or "do's and don'ts" that contributors should follow when customizing or extending the UI bundle?

  4. Community Readiness and Reception

    • How receptive do you think the broader Docs team and Fedora community would be to a UI/UX-focused customization effort?
    • What concerns (if any) do you foresee from stakeholders?

  5. Impact on Contributors

    • How might these UI enhancements improve the experience for new or existing contributors?
    • What other UI elements or interactive features would you personally like to see in Fedora Docs?

Details

  • User research with documentation maintainers and contributors
  • Learning about Antora theming and creating a development environment
  • Documenting the dev environment setup for future contributors
  • Implementing knowledgebase-style page customizations

Expected Outcome

Easier organization and structure for complex hierarchies of information in Fedora Docs, and easier authoring of short-form content that answers specific questions rather than requiring long, detailed pages.

## Summary Research and implement visual changes to the Fedora Docs Antora theme to better support knowledgebase-style content with complex hierarchies of information. ## Background Migrated from [commops/tickets#71](https://forge.fedoraproject.org/commops/tickets/issues/71), where significant research and community discussion took place. This is part of the Fedora Docs 2025 Initiative. The current Fedora Docs theme excels at presenting book-like, linear documentation but is less optimized for content structured as a knowledgebase — short-form answers to questions, deeply nested topic hierarchies, and cross-referenced content. Several CommOps docs pages (e.g., contributor best practices, team profiles) would benefit from a different page structure. ## Research and Discussion Completed Significant groundwork has been done by Chris Idoko (@chris), @pboy, @pbokoc, @ryanlerch, and Justin Wheeler (@jflory7): - **Antora/AsciiDoc research**: Chris Idoko explored pass-through blocks, UI bundle customization, and how .adoc files integrate with custom HTML/CSS/JS. He found the system is "almost identical to markdown" and identified two paths: AsciiDoc pass-through blocks or UI bundle customization. - **Interview playbook**: Chris Idoko drafted an interview playbook (reproduced below) for gathering structured feedback from documentation maintainers and contributors on the feasibility and direction of UI customizations. - **Docs Team feedback**: @pboy clarified that the proposal is about page structure (knowledgebase layout vs. book layout), not content changes, and noted that "a lot of preliminary work has already been done." @ryanlerch provided technical insights on the Antora theming system. - **Alternative ideas explored**: A complementary onboarding website ("My Fedora First Steps") was discussed as a curated entry point, separate from but linking into the main docs. - **CommOps meeting follow-up (2025-09-30)**: @jflory7 was to reach out to @pboy and Chris Idoko to determine next steps. @pboy confirmed the ticket should move to the Docs team tracker. ## Interview Playbook The following interview playbook was drafted by Chris Idoko to guide structured feedback gathering from documentation stakeholders: **Topic:** Implement UI/UX enhancements for a knowledgebase to Fedora Docs Antora theme **Owner:** Chris Idoko (FAS @chris) ### I. Purpose - **Objective:** Gather feedback from documentation maintainers, contributors, and interested team members on customizing the Fedora Docs site UI bundle to support custom HTML, CSS, and JavaScript. The current documentation infrastructure — based on Antora and AsciiDoc — follows a book-like format, which, while informative, does not offer the best experience for user interaction. - **Audience:** Interviewers (internal team members, volunteers, Docs teams, etc.) ### II. Project Goals 1. **Enhance the Documentation UI** — Implement customized UI pages within key sections of the documentation site to improve UI layout and user engagement beyond the default Antora theme. 2. **Improve Contributor Experience and Onboarding** — Provide clear, visually guided, and interactive content that simplifies understanding of the documentation structure, where to contribute, teams to join, and how to get started. 3. **Grow the Contributor Base** — Make it easier for newcomers to identify where and how to contribute through better information navigation, clearly marked contribution entry points, and a more intuitive knowledge base. ### III. Questions & Considerations 1. **Feasibility and Sustainability** - If this UI customization initiative is adopted, how feasible is it to maintain over time? - What level of effort would be required to support, update, and document the custom UI components long-term? 2. **Best Practices and Technical Guidance** - What best practices should we follow when integrating custom HTML, CSS, and JavaScript into the Fedora Docs site? - Are there known limitations or constraints within the Antora theming system that we should be aware of? 3. **Documentation and Development Environment** - Is there existing documentation for the Antora theme development environment? - Are there any guidelines, conventions, or "do's and don'ts" that contributors should follow when customizing or extending the UI bundle? 4. **Community Readiness and Reception** - How receptive do you think the broader Docs team and Fedora community would be to a UI/UX-focused customization effort? - What concerns (if any) do you foresee from stakeholders? 5. **Impact on Contributors** - How might these UI enhancements improve the experience for new or existing contributors? - What other UI elements or interactive features would you personally like to see in Fedora Docs? ## Details - User research with documentation maintainers and contributors - Learning about Antora theming and creating a development environment - Documenting the dev environment setup for future contributors - Implementing knowledgebase-style page customizations ## Expected Outcome Easier organization and structure for complex hierarchies of information in Fedora Docs, and easier authoring of short-form content that answers specific questions rather than requiring long, detailed pages.
pboy commented 2026-06-26 02:10:28 +00:00
Owner
Copy link

I guess this ticket fits better to the Quick Docs project Restructure Quick Docs. Unfortunately, we can't reference it from there.

I guess this ticket fits better to the Quick Docs project [Restructure Quick Docs](https://forge.fedoraproject.org/docs/quick-docs/projects/508). Unfortunately, we can't reference it from there.
pboy commented 2026-07-09 07:22:14 +00:00
Owner
Copy link

For further discussion we have to take account the tickets in QuickDoc repo:

Project Restructure Quick Docs

There are tickets about the graphical design as well as page restructuring as well as some implementation steps.

See also the Wiki page Project Restructure Quick Docs

For further discussion we have to take account the tickets in QuickDoc repo: Project [Restructure Quick Docs](https://forge.fedoraproject.org/docs/quick-docs/projects/508) There are tickets about the graphical design as well as page restructuring as well as some implementation steps. See also the Wiki page Project [Restructure Quick Docs](https://forge.fedoraproject.org/docs/quick-docs/wiki/Project-Restructure-Quick-Docs)
jflory7 commented 2026-07-14 14:25:04 +00:00
Author
Owner
Copy link

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

This topic was raised briefly near the end of the meeting. @pbokoc described it as a large project and asked everyone to review the issues and claim any they want to work on. A project board has been set up at https://forge.fedoraproject.org/docs/quick-docs/projects/508 to track the work. I noted that we should break the work into smaller pieces and encouraged brainstorming in the ticket — even if you aren't ready to work on CSS or UI changes yet, feedback on what improvements you'd like to see is valuable for when someone has capacity.

Follow-up:

  • Everyone: Drop a comment on this issue with your ideas, suggestions, or brainstorming for UI/UX improvements — the Quick Docs project board is available for reference
  • Ideas and suggestions are welcome even from those not ready to contribute code

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)._ --- This topic was raised briefly near the end of the meeting. @pbokoc described it as a large project and asked everyone to review the issues and claim any they want to work on. A project board has been set up at https://forge.fedoraproject.org/docs/quick-docs/projects/508 to track the work. I noted that we should break the work into smaller pieces and encouraged brainstorming in the ticket — even if you aren't ready to work on CSS or UI changes yet, feedback on what improvements you'd like to see is valuable for when someone has capacity. **Follow-up:** - Everyone: Drop a comment on this issue with your ideas, suggestions, or brainstorming for UI/UX improvements — the [Quick Docs project board](https://forge.fedoraproject.org/docs/quick-docs/projects/508) is available for reference - Ideas and suggestions are welcome even from those not ready to contribute code <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
Revamping Docs Homepage
Assignees
Clear assignees
No assignees
2 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#51
No description provided.