Possible Docs team work plan for the F39 / F40 period

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.

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

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

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

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

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

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

2 Likes

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

My recent comment in Simplify Docs Workflow organization page (#21) · Issues · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab is related to that.

I stay myself tuned to get used to how things are working atm :wink:

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.

1 Like

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.

1 Like

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?

1 Like

Ad:
6. Another area would be to attract new contributors. … https://whatcanidoforfedora.org

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.

1 Like

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.

1 Like

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?

1 Like

Ah, I’m not surprised. :smiley:

One needs to update the wiki page here and then the easyfix page is periodically regenerated after scraping from the necessary repos:

https://fedoraproject.org/wiki/Easyfix

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:

https://pagure.io/fedora-join/Welcome-to-Fedora

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.

Some thoughts about onboarding experience

Home page in your web browser

When opening Firefox after installing the Fedora, what you see when you open your homepage is
https://start.fedoraproject.org/

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.

Screenshot_20230420_222156

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’?

fedora-docs

We are working on it
https://fedoraproject.org/start/

It’s in an early development phase, but if you have some idea here, don’t hesitate to open a ticket or contribute on GitLab

2 Likes

Awesome. I will draft UI text and visualize ideas.

Slightly off-topic, but where can I find site map and information architecture to see hierarchy of Docs repos and URL by project?

A rough idea I’m imagining is an overview of site structure and high-level stats;

  • Antora / CMS
  • Project: Workstation, Server, CoreOS, Cloud, EPEL and so on
  • Docs repo: GitLab, Pagure, GitHub
  • Local build script
  • Number of members
  • Number of commits per month
  • Number of pages (to maintain)

The reason I’m asking this is to figure out user journeys and have a map-like visualization.

1 Like

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.

Standing by it.

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.

2 Likes

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.

1 Like

Issue ticket created here with UI text and image to share an idea.

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.
https://discussion.fedoraproject.org/t/possible-docs-team-work-plan-for-the-f39-f40-period/81122
discussion.fedoraproject.org
CC-MAIN-2023-40
100774
application/http; msgtype=response
sha1:TCIWGS2SLCCXJC6GSI7JEG2TWI3KX3Q2
<urn:uuid:bf1cd8c1-b031-4195-b285-6f5c441e4f79>
2023-09-23T03:24:20Z
184.105.99.43
text/html
sha1:FJVOBU7X23WXN7XWFZFSUYEQPDIXNHBM
<urn:uuid:920232a3-4d05-410c-9710-bde2c2a7c58a>
https://discussion.fedoraproject.org/t/possible-docs-team-work-plan-for-the-f39-f40-period/81122
response
<urn:uuid:a4487e3b-22d9-40bf-bdfb-830cb2b32018>
isPartOf: CC-MAIN-2023-40
publisher: Common Crawl
description: Wide crawl of the web for September/October 2023
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-154
software: Apache Nutch 1.19 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.5-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/