Now that Council has approved our Docs Community Initiative, we should get started. Here’s the proposal for the next 3 months:
Let’s discuss and decide on a work plan. A part of it is to complete the running poll to find a suitable meeting time, and to schedule a first „activity day” on Matrix in December. As a part of this discussion, we should update our mission statement and our definition of our goals as Docs team. Let’s discuss this in this thread.
We need to start discussing and checking the current status of our local authoring tools, create a plan how to improve them, and start working on it. We should have a sort of „wishlist“ ready by the end of January. As part of this effort, we will update our contributor docs. We will start aseparate thread for this.
Start checking our current docs, specifically Quick Docs. Please, contribute and write down your experiences, let us know what problems you have, and what you’d like to see improved – and also what you think is good. We should start separate threads for this topic and the following ones later.
Start a discussion about a new site hierarchy, based on categories and tags instead of the current structure, and come up with a working plan, including finding people to revamp the site.
Additionally, we’ll set up our Forgejo space. We’ll start with two ticket-only repos that will serve as trackers, one for team activities (workshops, conferences, etc.) and a second one to track our initiative work. The first one we may migrate from GitLab. We should complete this step within the next 2 weeks.
Migrate one of our document repos - either Quick Docs or Release Notes are suitable candidates. This should be done by mid-December at the latest.
Christmas is coming soon, which means a lot of people will be absent for a period of a few weeks, but even with that in mind the above should be doable by the end of February.
On this thread, are you looking for detailed input on this topic - or more for summarised items to put on the agenda for the meeting, where we’ll discuss the detail?
I’ll reply here in a higher or lower level of detail accordingly
Obviously, my notification configuration doesn’t work at the moment.
Nevertheless, the idea is to discuss and agree on an overview level, so on a summarize level I think. For details, we should create new detail topics. That’s the idea, but perhaps that is not practical either, and the levels cannot really be separated. When in doubt, we should discuss everything here and then split off individual topics if necessary.
Cool. Here are some summary notes from me about what we should look at:
Updating the mission statement (as you say), including why we think this is important. (“Making the system clearer and more accessible to all users” is one key aspect of it for me.)
Roles and responsibilities of the “Docs Team”, individual “Docs Teams”, and product teams (e.g. the Atomic Desktops team already do a lot of good work creating and maintining docs)
Ensuring sustainability and how we prevent obsolete docs hanging around without being updated.
Mapping out “contributor journeys”, particularly:
when someone makes a technical contribution and needs to document it
when someone identifies a documentation gap and wants to resolve it
Guidelines about using LLMs to assist in writing docs?
Should we look at Search Engine Optimization (maybe that’s an outdated term now, but can we do anything to get our official docs higher in search engine results?)
Technical areas (other than those mentioned in the initiative) that often generate questions on Ask Fedora and would be worth some documentation focus:
dual GPU systems (i.e. with both integrated and discrete GPU, not only Nvidia)
btrfs (specifically, the way Fedora has implemented it - not generic material that can be found in the upstream docs)
recommended supporting tools like btrfs-assistant?
Why not use Discourse for Fedora Docs? Ask Fedora is so popular that the same questions get asked and answered over and over again. Yet these FAQs don’t make it into Fedora Quick Docs. Ask Fedora contributors are potential Fedora Docs contributors. Make contributing as easy as replying. Categories are defined, HTML and mark down supported, search implemented, trust levels established, contributors logged in. What’s missing?
I vaguely remember seeing that suggested before, but there are some issues with that. Not everything can be easily explained in a forum post, and documentation goes out of date over time, so we’d have to keep reviewing old posts and delete them (or have someone with permissions edit them), and then older discussions would stop making sense, and… it’s a nonstarter, forums are great for Q&A, but not docs.
