Release F38 is now out, and we have a great new project site that presents everything to the public in a modern way.
I think this is a good opportunity to recalibrate our own work, especially given the existing, rather tight resources. In this regard, here are a few theses that we can perhaps discuss.
Given the continued low attention of documentation in general, it is abundantly inefficient, in light of the given resource situation, to continue to improve the general documentation pages, which are Fedora docs homepage, admin pages and quick docs. Instead, it is more efficient to focus on areas that already attribute a high value to documentation and present it accordingly to the outside world. At the moment, these are mainly Server, CoreOS, and IoT. The aforementioned former areas have been my main field of work so far. I would then focus on the latter areas instead, especially Server.
This means for the work of the docs team to focus (and limit) on improving and facilitating the creation of documentation contributions for the latter editions. Practically, to focus on improving our guide(s) for contributors. So in particular on the work contributed by @hankuoffroad. It would therefore make sense for @hankuoffroad to join the board so that accountability is also publicly documented and visible.
We should restructure Quick Docs in the manner of a wiki. Any FAS account would be allowed to comment on contributions directly. Several voices have advocated such a solution. At the same time, we would close all open issues and merge all open PR without further review. Afterward, Issues and PRs would be deactivated. The Docs team would in a preliminary final act only have to add to all existing posts the header with author/Fedora version/last review/ category and tags, so that we can remove the navigation bar. I could still do this task.
We should follow a suggestion from @py0xc3 and withdraw the outdated Administratorās Guide entirely and stop to continue to spread misleading information. There is no perspective to update it in the foreseeable future.
Moreover, it would be useful to deal with such documentation that has some acceptance in the Fedora universe. That would be the Release Notes. We should therefore tackle the project of automatically generating the release notes from the change proposals and aim for a first beta version for F39. @darknao would be particularly in demand here.
Another area would be to attract new contributors. One way to do this would be to update the site https://whatcanidoforfedora.org as discussed some weeks ago.
Not sure about the contents of your discussions of course, but indeed, this page links in the end at Join the Docs Project - Fedora Project Wiki which does not yet contain forwarding to the current team page, workflow pages, and so on. Maybe a first step could be to revise the wiki page with proper links?
After having been absent about half a year, I feel a bit lost myself because the current āstructures and workflow in practiceā is a bit hard to understand/identify, or alternatively said, reading the related Docs workflow pages confirm my past assumptions about how it used to be intended, which seem to be misleading/obsolete - not sure if that might also affect newcomers when reading that (?). My perception is that given documentations do not comply to the āreal worldā. However, we developed the original workflow to have some clear, common, formal point of start with which we can jointly go ahead to see how it develops and to adjust when necessary (which seems to have informally taken place! Thatās good I think?). So the documented formal origins might be adjusted to reflect the currently informal real world if the Docs have practically reached a workflow/structures that work out for all and that therefore keep stable (does it?).
Indeed, I think the current primarily synchronous flow, which seems to have its alignment centralized more informally in the meetings, could be even simpler and easier in a Docs page compared to the original intention (maybe a simplification for newcomers?).
Thatās pragmatic and doable. Totally onboard with Docs team work plan.
About your focus area, I think Server, CoreOS and IoT address high-impact user groups like enterprises and cloud hosting providers that offer Fedora images or give a user guide how to run other Linux VM images.
I sketched out Docs wishlist recently. One of key topics in my mind is resources for enterprise users and cloud developers due to a growth of CoreOS users and cloud engineers/certifications.
Just curious CoreOS and IoT docs are in GitHub. Do you know if there are many active contributors and anything we can learn from them for synergy?
Regarding a nomination to join the board, Iām grateful to such recognition. Thank you. Iām not sure what it takes to serve as the board. If thatās all not too overwhelming for me and my ability, Iāll wait for vote result or discussion/feedback.
I could contribute to Docs with a primary focus:
Onboarding improvement: how to get help and involved, onboarding experience (new web site and visibility)
Weekly update
Ongoing update of QuickDocs
Enterprise user content: EPEL and CoreOS
The above is influenced by personal interest, my skill set from day job, and impact to Docs. I hope this fits in well with work plan @pboy is envisioning.
Following on from discussion during weekly meeting 2023-04-19, please allow me to elaborate more about the point 3 and 6, so we can follow them through incrementally outside meetings as well and we donāt need to wait for the next meetings.
Restructure of QuickDocs
Comment on contributions directly: I could think of post-PR comments. If Iām mistaken, what do you mean by that? I want to understand what is current status and what changes you suggest.
Close open issues: Iām not sure I agree with this. There is no harm or stigma attached to reality that we have open issues (either technical reviews or full rewrite). Unless an issue no longer requires technical reviews or rewrite, we need to keep them and look for subject matter specialists to help out and bring content back to life.
Update the āwhatcanidoforfedoraā site
I guess this will be one-off tweaking required by someone who has experience (is it you @pboy ?).
Playing devilās advocate, in competitive world of search results and expectation on glossy presentations, what else draws peopleās attention to volunteering or āgigsā more effectively than a microsite? Why donāt we combine our efforts in the website 3.0 and discuss how to measure site performance?
My suggestions: Share and talk about the documentation and stats in our communication channels - weekly stats (just like CPE team) in Discussion
Source of data to track users and contributions: After all that efforts to attract contributions, we need data source to track users registered and commits. In GitLab, we can use analytics > repository statistics. In Pagure QuickDocs, Author Stats are shown (how many contributors are registered and commits). GitHub repo/project (CoreOS docs and so on) also presents stats in the following menus insights tab > pulse / contributors. GitLab and GitHub give the best out-of-box analytics dashboard for users and commit stats.
i think wcidff has been quite out of date for a whileāworth updating if it isnāt too much work.
Other ideas/queries:
are docs issues being listed in the easyfix list? Fedora Project easyfix (looks like my CSS etc. isnāt loading here for the page)
weāve got quite a few folks on the āwelcome to fedoraā process that have indicated theyād like to participate in documentation. What can we do to get them more involved? Issues - fedora-join/Welcome-to-Fedora - Pagure.io
The welcome to Fedora process is sort of the go-to now for new comers, so making sure we direct folks interested in documentation to the right place (here?) would be a good low hanging fruit type task.
Last time I asked about this website, the Council decided to retire it and redirect to Welcome to Fedora! :: Fedora Docs
So I donāt think itāll be updated anymore. @t0xic0der do you have any news about this decision?
The pages are completely outdated and need a complete overhaul, including all links. But just these links are interesting by the way. They show which wiki pages are completely outdated, but still active and spreading outdated information. In the course of an update, these old wiki pages have to be reworked as well, mostly hopefully by redirecting them to a current docs page.
Otherwise, my point about this site is twofold. First, as far as I know, it is the only place where all the possibilities of contributions are listed and briefly presented. Otherwise, this is completely scattered in various places. And secondly, the style is not so ādry and boringā, but somewhat humorous and āsomehow differentā, and thus hopefully gains its own appeal.
I think, it will be necessary to check the site with each new release, i.e. twice a year. And yes, I have some experience. And I would also find it ācoolā to keep the site going.
After we discussed it some weeks ago start a discussion with Council about it, and they reverted that decision.
It would be nice to know how to update easyfix page.
When new contributors sign up on Fedora Join, could the FAS send out onboarding email?
atm, I canāt interact with them for onboarding. If they made introduction, it needs to visible. I canāt find it.
Yes, they are. But the easyfix list itself needs a fix. It refers to some pagure.io repos we no longer use. And Iāve the impression, the new gitlab repos are not included.
Most interesting. I think, discussion would be the right place, yes. The Matrix channel another one. And maybe, we should create a special, kind of greeting page for new contributors?
So, newcomers donāt sign up on Fedora Join. They create a Fedora account, login to pagure.io and then we create a new āwelcome to Fedoraā ticket for them so that they can interact with the community and vice versa all in one place. The process is documented in the readme here:
So what we do is watch this repo so that when a new āwelcome to Fedoraā ticket is opened we get a notification. Any one can open a new ticket, it doesnāt have to be anyone from the Fedora Join SIG etc.
(The tickets use a pagure template to provide users with some general info about Fedora. Please do go through it and suggest improvements)
Thatāll be great. I think most SIGs have a page that lists their communication channels, so even something like that would doāit just has to tell folks where to find the docs team.
I stumbled upon the magazine because it is the most eye-catching onboarding experience to start with the Fedora project. Within a few days of my first installation of Fedora Workstation, I made an article proposal to Discussion and got accepted. Thatās where my crave for documentation started.
I think in the new website 3.0 a similar user journey will help onboard new users, no sweat.
Not sure if that is going to be changed to the website landing page.
Banner
Instead of cramming with āDocumentationā on top right corner of the new web site category labels, why not requesting for a banner to display the new Documentation logo with some text āJoin usā?
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.
