owned this note
owned this note
Published
Linked with GitHub
# Google Season of Docs 2024 - Fedora proposal
## Proposal Title
Content conversions of top posts in Ask Fedora into Quick Docs
## About your organization
The Fedora Project is a community of people working to build a free and open source software platform.
## About your project
The Fedora Documentation Team coordinates the content and tooling of the documentation at docs.fedoraproject.org with contributions from the broader community.
As a general rule, the Fedora documentation follows the structure of the Fedora distribution, which is grouped by editions such as Workstation, Server, CoreOS, IoT, and so on. What's more, there are Quick Docs, a collection of short How-To guides that address user questions and describe solutions, which are agnostic to editions.
Problem Statement:
Way back in 2019, a large body of Quick Docs was auto-exported from wiki pages. Over the years, contributors made enourmous efforts to carry out technical reviews. As projects evolve, documentation writers and reviewers of Quick Docs didn't keep up with the following aspects;
- feedback from users and solutions found by helpers in Ask Fedora
- new releases and breaking changes of upstream packages
Ask Fedora is a vibrant Q&A forum where users find solutions or ask about installing, using, troubleshooting, customizing, or upgrading any variant of Fedora Linux. Finding pertinent information in Ask Fedora is often harder than it needs to be.
## Your project's scope
Project's goal:
1. Focus on the best possible use of the pool of questions and answers in Ask Fedora.
2. Create a documented workaround by consolidating related troubleshooting information with a solution (or fix) and the description of the problem.
3. Initiate concerted effort of converting top posts into Quick Docs as a continuing workflow. This way, users are likely to self-serve issues they encounter when using Fedora Linux. Furthermore, we create documentation culture across the broader community, rather than one-off exercise.
4. Assess unanswered questions on a selected sub-category based on a friction log, poll/interviews with subject matter experts in Fedora Project, and upstream documentation.
- Shortlist commonly asked topics in Ask Fedora and select one sub-category in Ask Fedora that will help resolving recurring and unanswered questions.
One of the most recurring and open questions in Ask Fedora is multimedia issues. We could take audio issues as a first phase, where we extend it to other content topics as the continuing project.
Link to Ask Fedora Posts (Audio): https://discussion.fedoraproject.org/tags/c/ask/6/all/pipewire?ascending=false&order=views
- Create a friction log
A friction log is a journal in which you try your software as a user would and document your experiences. Pick a user and a scenario with a clear beginning and end. For example, a new user connects a Bluetooth headset to Fedora Linux Workstation for the first time. Note the scenario and any other test information at the top page, such as the test environment or kernel version you're using. Please check your findings with a solution (or a fix) in Ask Fedora.
- Audit Fedora Quick Docs repository
Link to Quick Docs: https://docs.fedoraproject.org/en-US/quick-docs/
- Develop a roadmap: content planning and project tracker
- Create a Recovery Plan: refer to a project goal to achieve and build a plan to improve content and participations from the broader community
- Liaison with reviewers and subject matter experts
## Measuring your project's success
- An increase in content conversions of top posts in Ask Fedora that turns into docs PRs from the original commenter or participants. This almost never happens currently, so initiation of content conversion/reuse would be a great indicator of success.
- Reduction of related posts on similar issues: helpers in Ask Fedora can provide a link to most relevant Quick Docs articles.
## Timeline
May
The writer will receive guidance on navigating onboarding documentation to gain a thorough grasp of the Fedora project's scope and user base. Upon completion of this phase, the writer will become fully integrated into Fedora project processes.
June - July
The writer will work with the Fedora contributors in order to collect the most important answered questions in Ask Fedora platform. Then, will contrast the existing Quick Docs articles with the answer to understand which ones are missing or require an update.
August - October
The writer will work on the documentation needed for Quick Docs based on the compilation of answered questions from Ask Fedora platform. The documentation team volunteer will work with them to review and publish the articles.
November
Wrapping up the project completion.
## Additonal information
Previous experience with technical writers or documentation: There are technical writers that volunteered as mentors in the past.
Workflow:
Information on Quick Docs follows the PR (peer review and pull request) process. The new article published as a result is served as a single source of truth listed on the official Fedora documentation website.
Recommended Docs Tooling:
Text editor, AsciiDoc, Git, Command Line Interface, set-up of local writing environment, linter, Podman/Docker, obviously, Fedora Linux Workstation or rpm-based Fedora family distributions (any desktop environment of intern's preference)