Some time ago we discussed how to improve the Release Notes generation and opened (and discussed) a Fesco ticket. Fesco will discuss it today, 17:00 UTC #fedora-meeting irc.libera.chat
On your workstation you may use:
date -d '2022-09-27 17:00 UTC'
We have a discussion on the FESCo ticket about the best way to handle the sections of the release notes in the Change Proposal form: using wiki categories or just text lines.
Please, could you have a look at the FESCo ticket and discuss here what our preference is?
Ticket: Issue #2868: Release Notes Improvement - fesco - Pagure.io
1 Like
Hi @pboy, thanks for leading this discussion.
I read through the FESCo ticket and also came to the same conclusion about tags/categories for Release Notes in Change proposals. Working in a part of Fedora like Docs makes you realize how vast Fedora is, and it is a hard responsibility to classify and organize everything about Fedora. Extra metadata like category tags in Change proposals reduces the cognitive cost to determine information clusters and properly highlight a Change in the Release Notes.
In addition to Changes on the Fedora Wiki, I wondered if direct inclusion would also help the Docs Team participate more equitably, as key stakeholders of Fedora Change proposals. For example, what if the Fedora Change Wrangler opened a new Fedora Discussion thread with the proposed release notes from a Change proposal, once a Change was approved by FESCo? FESCo approval is generally when we are more certain that a notable change will advance in Fedora. The Docs Team would then have an opportunity for open discussion before the release freeze, which provides advance time to ask questions, get more context, and seek clarity about a Change.
For direct inclusion to be helpful, I believe it depends on how the Docs Team most prefers to be engaged. Where would updates on new release notes best be shared? Chatting on Matrix? Shared in a meeting? Opening a ticket? Starting a Discussion thread? If there is a clear, best way to engage with the Docs Team, I believe we could take the next step to work with @bcotton and the PgM Team to propose a new step in the Change Wrangling process.
What do you think? Would direct inclusion in release note discussion be helpful? Or do you think there is a better way to help the Docs Team write early and write often with the Release Notes?
The process already includes opening a release notes issue when the Change proposal is approved. That’s what I’d consider “direct engagement”. Creating a Discussion thread seems like unnecessary duplication. If that’s desirable, you can run an instance of the bot Matthew wrote for Council tickets. Adding additional manual steps seems like a regression to me.
edited to sound like way less of a jerk than I did in the first draft. sorry
1 Like
To my understanding, it’s really not a matter of engagement, but more about manpower.
We are just not enough in the team to take care of every single release note at this time.
Just looking at tickets or opened PR, we can rather quickly see that’s not working very well.
Thanks both, this is helpful context.
A follow-up question I have as someone unfamiliar with Release Notes is how they are organized. Where would a newcomer look first to get involved with Release Notes? Should they work in specific repositories, subscribe to specific lists, set up a development environment, or a mix of these? Is there a step-by-step guide for how I would take a release note, review it, and incorporate it into the Docs site?
We have a few guides available on how to contribute to the documentation, and one more specific to release notes
Hi @jflory7 , thanks for contributing ideas to cope with and improve our current situation.
I think you hit a central point, the “stakeholdership”.
And more automation certainly helps with our scarce resources. We already have a lot, as Ben pointed out. But it could be helpful if e.g. with the final decision about accepted changes, or beta freeze a thread in discussion would be started automatically.
Currently, we all know that the next release notes are looming on the horizon. But the horizon is always far away.
Thanks for these links. I see a lot of “how” documentation but the “what” and “where” seems less detailed. For example, as a new contributor, it is hard to figure out exactly where I should put my foot forward first, just because there are so many different ways to participate. I might know how to set up Antora and know how the docs contribution process generally works, but it is more difficult to find a first place where I could apply that knowledge.
In line with the ongoing discussion about Fedora’s next five-year strategy and everyone in Fedora either having a mentor or mentee, I wonder if there is both interest and capacity in offering Docs mentoring to new contributors. Could a new contributor get matched to an existing Docs contributor? It doesn’t have to be a “forever” mentorship, but it go for a month or two, or for one Fedora release cycle.
While automation and tooling play important roles, I also wonder whether we might be focusing too much on automation and tooling, before we have clear processes and pathways for people to contribute to Docs. There is a lot of docs on how to work on docs, but there is less guidance on pathways of how to go from “zero to hero”, as the saying goes.
Out of curiosity. Does the Docs schedule tracker accurately reflect the timeline that the Docs Team is working in today? I noticed there are a lot of milestones about release notes, but I was curious whether these milestones are actually met during the release cycle, or if things typically pile up at the end.
https://fedorapeople.org/groups/schedule/f-37/f-37-docs-tasks.html
We should really fix that. Probably we should add a section like “How to become a docs writer and contributor” (hopefully with a more snappy title). Part of it could be a kind or mentoring program.
What could be inside such a “How to …” text? We could start a text in our staging environment (Fedora Documentation Team :: Fedora Docs Staging) or can start a text on hackdm.io
Well, we have a work plan in the back of our heads, so to speak. And the link you refer to is nice, but we never talked about it in the last 6 months or so, at least i can’t remember. For now, we’re relying on our division of labor. And release notes are taken care of by pbokoc. That’s probably part of the “stakeholder” issue.
We are still struggling with the basics. Currently, our biggest project is the publication of a renewed docs homepage with release 37. But that has more or less nothing to do with the plannings you link to. It’s a parallel evolution.
I am thinking aloud here. But do you think it would be possible to identify the top three ways for someone to contribute to Docs? I can think of release notes and Quick Docs as two such examples, but perhaps it would help to lay out a few contributor pathways that someone could follow in order to “level up” as a Docs contributor. When you are fresh at the gate and trying to figure out where to start, having a clear pathway could help demystify where to begin.
Do you (and/or the rest of the Docs team) think a tool like this would be useful? For me, a view like this helps, but I think firstly it should be useful for the core team. If it isn’t useful, perhaps we can deprecate it.
I’m not sure if this is something @pbokoc follows as part of his process for release notes?
I’m using it, and I find it useful. Please don’t deprecate it (yet) 
.I think there are maybe a few tasks in it that we don’t really do anymore, or don’t strictly follow the mentioned schedule.
We are also currently trying to use the Fedora group milestones available on GitLab for more or less the same purpose.
To be clear, it is not a power I want to dictate what stays or goes. Whatever decision is reached should be made by members of the Docs Team. 
Do you think both of these tools (i.e. the schedule tracker and GitLab milestones) should co-exist, or should one be deprecated eventually in favor of the other?
I’m think aloud, too. Why may someone want to contribute to docs?
- Someone ma have solved a specific problem or a special need and may want to share it?
- Someone wants to get engaged in Fedora but has no technical skills?
- Someone may wan to improve a piece of documentation?
What we can do?
- Release notes and a release note how to is a good occasion, for sure. We have somethin in place.
- Maybe we could make “wishlist” what we think is needed?
- Should we call for help for a specific topic (on userlist, matrix, etc)
- Should we introduce a kind of “office hour” for open discussion and getting to know each other?
Currently, we so busy with everyday tasks, that we don’t get to plan and organize for the long term., unfortunately.