I’m with you on the idea about the links to the team page.
Link to the team page
My take-on on this is users need to get to the Docs team page or Docs repos, straight from the new landing page without concurrent steps, microsite, registration or labelling process.
The most striking way is like the Magazine team with clear roles displayed;
Propose a new article
Become a writer
Become an editor
Communication flow
I don’t see a change in the way Docs team interact for the last few months. Based the workflow documented in 2022, no one suggested a change. Maybe ‘by the book’ does not exist. We can’t change the natural and preferred way of communication of an individual. One could prefer PR/MR review comments (concise and to the point, get the job done), Docs meeting, social hour to walls of text and rhetoric in Discussion.
We planned on killing and creating redirects for both whatcanidoforfedora.org and Fedora Project easyfix. The L&F for the latter is understandably broken due to the recent move of assets to make way for the newer websites.
They most definitely would require reworks, I agree but up until the time that happens, I suggest that we go ahead with setting up the redirects to avoid providing obsolete information to whoever visits that page.
It is more of a practice issue than a technical issue of the site. You see, for the website to actually be helpful - we need people to tag the issues of their repositories with the easyfix label and for the most part, this never took off as if things were easy then either they were taken care of in an instant by someone experienced or were left alone as low-hanging fruit and deemed unimportant.
I remember @bcotton having said that, yes as long as someone takes ownership of it. Like I said in my previous reply if this is something we can still make use of in a modified form - it is totally fine for the docs team to go ahead with it. A redirect was proposed to make sure that by the time the rewrite of the page comes up - we do not have something awfully unmaintained and broken (in case of the Easyfix site) there.
We have so much inappropriate and outdated information on the Fedora site, there is no need to rush here. Putting a rewrite on the WIKI pages wcidff is linking to, would make the renewing work much more complicate. Many of these pages have a high visitors rate. They are very popular. I would prefer to check the page step by step and then decide, what to do. There are several options, redirect to a docs page, migrate (and update) the page to docs, keep the page and update, keep the page as is (some are quite up-to-date), etc.
Instead, we may add an admonition that the page is under review and may contain outdated information.
Yeah, we should include that page in our release cycle workflow. So should introduce a regular check at each release time.
I think, another important thing is communication. Maybe we should rename “easy fix” to something like “good first task”. And we have to propagate this (and other items we have). Fedora is good at hiding its jewels. E.g we could “advertise” these things on our central landing page. Instead, we make the same mistake again, we mainly offer downloads, nothing else. Compare our site with e.g. netbeans.org, opensuse.org, debian.org. We make the same mistake again and again. And complain about missing contributors, again and again
Yes, of course, Docs team should take ownership. And above I have listed the reasons for this.
Very informative indeed and I share his view on many aspects or can understand it.
And I feel confirmed in many things that I have advocated in various discussions
Fedora needs to pay more attention to documentation and promote what we have wherever it fits.
Fedora has a very idiosyncratic culture that makes it very difficult to join.
Fedora is very good at hiding its jewels and very limited in giving a good overview. In this respect, a continuation of the wcidff site would be helpful.
I think your view point is far from constructive. Instead, we could drive it more positive manner even when your critical thinking is lingering.
Promotion: We could suggest better user journey and messaging in the new website, so users can find signposts on Docs easily.
Joining instructions: I think a difficulty to join is partly due to discrepancies in various Docs team pages, README.md file and wiki, which need de-dup and spring-cleaning to strive for consistency. I’m working on CTA (Call to action) on the documentation landing page to link role-based joining instructions. We can discuss more over next days. @glb@darknao already gave good feedback on GItLab issue board and Discussion.
Website UX: The web site is not set in stone. It is ours to shape up and build. All is encouraged to make suggestions and share mock-up images, so we can improve. Without (constructive) feedback, we can’t change.
I guess you’re confusing analysis/diagnosis and action/reaction to analysis at the moment. My post above and the post of sampsonf is about analyzing the situation (and an analysis is not about constructive/not constructive, but about accurate/not accurate).
Your suggestions deal with (constructive) measures on the diagnosis. And there we are largely in agreement. And I have - by the way - not only made plenty of constructive suggestions, but also made plenty of constructive contributions.
Diagnoses here: We made exactly this for over a year – with limited success. On the original published new landing page, there was nothing about documentation. Your recent intervention has brought a significant improvement. But there is still a long long way to go.
Yes, but I think that is the least urgent problem we have. And all the work is wasted effort if no one notices Docs because we keep it ‘well hidden’.
My (constructive) proposal here: Concentration on such documentation, which is just not hidden, but is actively in use by relevant others - the 3 editions I mentioned. In this way, the work achieves impact and does not fizzle out.
There was a lot of constructive feedback, and much of it is included - anything to do with downloading (a bit of an exaggeration). This was obviously plausible for most of the actors. And you need a broad consensus in the community to change, e.g. the website in its structure. As far as documentation is concerned, there is no broad majority for that at the moment, just like for everything else that doesn’t need a compiler (also a bit of an exaggeration). About a (constructive) concentration on the editions mentioned, hopefully over time a correction can be achieved.
Now here’s the thing. The WCIDFF rewrite does “not” need to be a 1:1 functionally identical to its former self. We could totally have it self-contained to have the resources, thus eliminating the dependency on the wiki pages that this rendition of WCIDFF links to. If there is no dependence on those pages, those need not be updated or at least can be updated slowly - thereby concurring with your point.
Not sure if I agree with advertising the “easyfixes” in the central landing page but we could totally do something to promote the opportunities to contribute - like we already have in this rendition of Fedora Websites 3.0,
I will circle back to my previously posted point again. If we were to go looking for “easyfixes” - I am certain to find at least hundreds of those strewn across a variety of projects belonging to a bunch of SIGs, teams, subprojects etc. The thing is, most of the time, it is either deemed unnecessary to mark them out as issues as they are so self-contained that one could solve them over coffee or so unimportant that they are left open like a low-hanging fruit for many years. Having these shown up in a primary place would not make a good look for us is what I am going to say.
I think this is more a human issue than a tooling issue tbh. I’ve filed this on the join SIG’s tracker to discuss how we can ensure that community members remember easyfix when triaging issues:
I’m not sure whether I understand you completely. If we revise WCIDFF, I would possibly be the only one working on it, but pretty sure one of the ones doing it. And I’d start by going through and correcting / updating the target links so that completely incorrect information is no longer conveyed. And in doing so, also either redirect the WIKI page, or some other appropriate action. The idea is to ensure that valuable information is not lost. The next step would be to consider further improvements or changes.
Whether we can or should make them completely independent would be something to consider. Your argument is attractive. Against it would speak, that the expenditure rises, and we would have to arrange contact to a WG, SIG, or team in the end nevertheless.
The first and most important action, in my opinion, would be to replace the erroneous and outdated information.
I would like to try to briefly summarize the state of our discussion for our meeting today.
Item 5 Release notes
We agree to start our project of (semi) automatic generation from Change Proposals. Then we would need to do some concrete planning now and agree on who will work on it.
Item 6 WCIDFF
We agree to start on this.I would be willing to take care, but a few collaborators would be helpful.
Item 3: Quick Docs
The idea now is not to give everyone direct commit authority, but to maintain a formal review for technical functionality with Antorra per PR. For now, we would abandon both any efforts to ensure quality and to update the existing texts.
We would then have to agree on who would take care of the PRs.
It’s also still open, if we want to add category and tags to all existing texts in a hero action and then abandon the navigation bar.
We have not decided yet:
Item 4: Withdraw Administrator’s Guide
Item 2: Focus on the documentation of the editions already presented as important and also for a wide audience
Itemt 1: Visibility of documentation, do we want to simply wait for the evolution or do we want to start now to achieve improvements and acceptance there.
In discussion there came up 2 additional topics
Item 7 new: Is it useful (and necessary) to simplify our workflow?
Item 8 new: Does it make sense to deal with the GitLab Web UI now, which is currently subject to ongoing change, and moreover may not have any beneficiary at the moment, since the documentation that resides on GitLab is not currently maintained at all, or at least not by people outside the Docs team.
I’ll open a topic for that this week. With regards to what @pboy summed up to “Casual GitLab Contributors” (and on the other hand, the audience that will not be interested or capable to manage gitlab at all), I think we are back to not just ask WHAT guide to show on the Docs pages but also ask IF we show a guide.
Therefore, I think it makes sense to interrupt the dedicated discussion on how to adjust or develop the GitLab guide and focus first on the “THAT it is possible to contribute, WHY, HOW, WHEN, WHERE” questions with regards to the points of interaction: that discussion might end up in an approach that already answers the IF and WHAT questions about the GitLab guide as well.
So, what I mean is to integrate the “IF gitlab guide” question into the wider discussion of the point of interaction with people to get a holistic approach/strategy. Concerning the “WHAT gitlab guide” question, I think only one approach was left in discussion anyway (the one from Hanku), while the other two already end up in the “IF gitlab guide” question being answered with “no” (feel free to challenge that if I misinterpreted the distributed discussions about that). This would then integrate item 8 for now.
I think there is no issue to reach a consensus in discourse. There was a time when we intentionally wanted to reach consensus asynchronously at GitLab or Discourse to mitigate the issue that occurred today in the meeting
Shall we also try to reach a consensus about the other items here? I would be +1 for item 7 (I think I elaborated my points already somewhere ) However, before doing something about item 7, it might be worth to first elaborate the point of interaction approach/strategy?
I would be +1 in item 4.
I cannot say much about item 2 at the moment (I’m still in the “coming back” phase ) , but if there is a clear consensus of the team, I will not resist to approve in order to avoid further postponing.
Concerning item 1, its the same as in item 2. But it could be worth at this item to also start with the point of interaction approach/strategy?
before we are sure about what to show on point of interaction, we need to pause the development of GiLab guide. Yes, that’s no problem for me. Let’s stash it for now.
With regards to what @pboy summed up to “Casual GitLab Contributors”: do you reference item 7 and 8? No urgency. We need to wait for regrouping and reprioritizing our actions due to unexpected departure of one great board member, @darknao - huge thanks for your help in many ways!!
On the other hand, I feel stifled by inertia and being numb after the meeting. We need to wait until next time (don’t know how long) and right time to restart the discussion. Cheers!
No worries. Feel free! From my side, nothing is urgent. I just wanted to offer the possibility
This refers only to point 8. So, @pboy and me saw together two groups: one GitLab-experienced people who need at the best the GitLab Docs, or people who are overwhelmed by GitLab and might be deterred if the new UI and its steps up to the MR is presented as average activity. If I got you right, your approach was to offer people the possibility achieve initial git(lab) experience and get deeper understanding of git(lab) while working on Docs. Your approach seems to be the only one where an audience could be possible if we get over past discussions (which are indeed no longer fully relevant), but there were questions (?) about if such an audience ends up on Docs pages with their search queries / their intentions or if we can make them to do so, but that might be integrated at the other topic later
The way WCIDFF works right now is by giving folks a funnel that they can pass through by selecting a list of things that piques their interest. The endpoint of this funnel is, of course, some wiki page that most likely consists of outdated information. With the redevelopment of the project, what I meant to say, is you could totally phase out the aforementioned workflow to come up with something that is a lot more streamlined and self-contained[1]. Say, for instance, you could have a list of cards pointing to the different SIGs, workgroups, and subteams with a small list of expected competencies required to participate and the place to reach out to for collaboration.
This tells me that you did understand what I conveyed previously. Most definitely, the replacement of the pages consisting of obsolete and mistaken information is one of the first things to do here. At least, having them detached from the WCIDFF can help to begin with but I am gonna let you choose how you plan on doing this.
A self-contained project might not necessarily be an isolated project here because as much as we need the assistance of the fellow SIGs, workgroups, and subteams to fill in the information, we need to ensure that we are not overly dependent on having perfect documentation to lead them to, etc. ↩︎
Given the discussions we had in matrix, I think we should postpone that topic and focus on the other open questions. I will wait with opening the topic until the next meeting. I will keep it in mind, but the more pragmatic stuff might need decisions and considerations first
) However, before doing something about item 7, it might be worth to first elaborate the point of interaction approach/strategy?
) , but if there is a clear consensus of the team, I will not resist to approve in order to avoid further postponing.