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)
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.
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.
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.
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
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.
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.