With regards to the low attention and attract new contributors points, I suggest to read the comments posted by Sampson in the other topic. Many of his points are independent from the casual contribution guide, and could have links to the low attention / absence of newcomers. I have myself just started to analyze his points, but in any case, they offer an unbiased perspective from outside the permanent Docs’ “core”: Please let us know: How to improve the guide for casual contributions in Docs? Which possibilities in the new GitLab suit you best? - #7 by sampsonf
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.
Sure, it is still a long way to get to ideal state. Text alone can be easily amplifying for misunderstanding. Now, I’m better informed.
I spend more time on the Website 3.0 repo than before, so I will continue to make suggestions and wait for feedback.
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.
1 Like
+1
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:
https://pagure.io/fedora-join/Fedora-Join/issue/286
Any other ideas are welcome.
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.
1 Like
I don’t see a problem with the interim plan and PR workflow. The Quick Docs guide already states PR workflow.
Until we have a minimum number of attendees on the Docs meeting, we need to postpone any decisions on other items and additional topics.
I’ll continue ‘business as usual’ work that I can contribute to regardless of the Docs meeting adjourned or not.
- Support engagement across point of interaction: I will wait for @py0xc3 's availability for consensus.
- QuickDocs: Prioritize PR opened and old issues to close (pending discussion)
But anything that needs vote or consensus will be delayed until further notice. I have no particular idea for the rest of items now.
1 Like
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?
OK, you mean
- 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
I try to extract from our discussions in this and in other threads a proposal of how to proceed.
-
The Docs Team concentrates on those documentations which already have a lot of attention: Server, CoreOS, IoT, SilverBlue, and Quick Docs. The responsibility for the editions falls to the respective working groups. The Docs Team can only improve the preconditions for contributions.
-
Main focus is to facilitate contributing to documentation and to re-vitalize the documentation contributors group.
- Improvement of contributors guides, especially Web based editing of pages in Pagure (used by Server and Quick Docs, we don’t support Github based documentation yet) and local authoring environment.
- Initiate various actions: CTA, writing hackfest, cooperative writing and alike to attract more authors.
Lead: Hankuoffroad (proposed, no commitment yet)
-
In terms of content, Docs Team focuses on Quick Docs. A first step is to improve the preconditions for the community initiatives corresponding to 2). This includes
- In one go, conversion of all contributions to the category system including elimination of the navigation column, introduction of the new header data, as well as elimination of the partials, as far as they are not actually shared.
- Improvement and completion of the Quick Docs Guide, esp. the list of categories and tags.
Lead: pboy
-
Docs Team takes over the site https://whatcanidoforfedora.org and updates the content (i.e. essentially the links)
Lead: pboy -
Improvements to the release notes are deferred until required resources are available again.
Just an idea to help our decision making easier, I could pull some data on five editions and Quick Docs such as recent contributions, number of edits (commit and PR merged), pages edited in last 12 months.
IoT and CoreOS documentation are in GitHub.
On topics 2- 3, I think it is fair to wait for other members to give comment.
I think, that would be very helpful. Do we have also data about visits, too? And can we compare the number of visits and the number o)?f downloads (percentage of docs visits related to downloads
Yes, IoT and CoreOS are on GitHub but we can support via local authoring env. Currently don’t know where Silverblue and Kinoite are.
Hello Peter, I’ve sent you a last 12 month data on the number of visits (clicks and impressions) extracted from Google Search Console.
About downloads, I recall release party (F35-F37) starts with downloads stats. I don’t know how to get such data from Fedora messaging bus as yet. I’m learning on data discovery from data sources and APIs. Maybe the presenter (@mattdm @bcotton) knows where to get it.
Silverblue doc is on GitHub. Kinoite doc is on Pagure.
About point 2 - contributor guides and reaching out to prospective writers,
CTA is a systemic way to show what documentation contributions there are and how to join. The link has issue ticket opened.
Triage by subject matter specialism
However, CTA is not effective to meeting demand for technical reviewers for articles that are outdated. We could find list of subject matter experts from previous contributions, various working groups and dev mailing list. We just need to reach out to them for volunteering technical reviews (without long-term commitment for maintaining docs) based on topics. Reviewers in Quick Docs are already doing this. We just need to scale up by subject matter specialism in respective working group.
- what are top 10 most asked questions in Ask Fedora in last 12 months? (installation guides)
- what are top 10 viewed pages/search keywords? (No 1 viewed page is EPEL)
Our messaging needs to be tailored to existing contributors. So CommsBlog or Discourse may be a better medium to reach right people.
Collaboration with Join SIG
Instead of overcrowding the Docs home page with banner (space constraint and potential objection to the idea of CTA banner), we could team up with Join SIG to onboard prospective members who are interested in various Docs contributions - UX, technical writing and workflow specialist. I dipped my toes into Join SIG already.
https://pagure.io/fedora-join/Welcome-to-Fedora/issues
Contributor guides
We have some guides. If anyone volunteers to improve them, I appreciate it. Imperfect guides have been an opportunity for me to tweak and improve the guides, and practice Git workflow. I’m happy to answer any questions from users and prospective contributors.