Google Season of Docs program 2024

Hi team,

This post is for upcoming application to Google Season of Docs program in 2024. Mindshare team (@ffmancera , many thanks for wrangling with Docs team) kindly has brought this opportunity to Docs team in advance at Matrix Docs room earlier in March.

Google Season of Docs is a mentoring program for “open source projects to improve documentation and helps professional technical writers gain hands-on experience in open source”.

In the meantime, we should come together and make a parallel blueprint and put it into the application form.

Depending on priorities in documentation and in most cases, scope of collaboration with Google Season of Docs requires close coordination with relevant working groups in Fedora.

@ffmancera provided a template application form in HackMD, so anyone can add input.

Deadline for organization applications: April 2, 2024 at 18:00 UTC

I made a suggestion to revamp system administration guide.

We need input from various working groups in addition to Docs members/boards to properly assess priorities and decide a topic that greatly helps improving documentation page.

Action

For Mindshare and Docs team to consider your input, please make suggestions as to how we could improve documentation in HackMD template by 2024-03-28T18:00:00Z.

You can put forward an idea other than system administration guide if you believe there are other priorities we need to focus on.

Thanks for your attention.

2 Likes

Added mentored-projects-team

A topic for Google Season of Docs application might be changed to something else other than sys admin guide due to the following reasons;

  • Docs team discussed a plan to have a series of shorter, topic-specific documentation that would gradually be supposed replace sys admin guide. No actions taken yet.
  • We haven’t agreed on clear needs to have system admin guide for Fedora Linux.
  • Most of use cases will be Server, which is maintained by Server Docs.
  • It is not feasible to agree to revamp sys admin guide before submission date on April 2.

Let me and @ffmancera know of your opinion. If I don’t hear from anyone else until 2024-03-28T18:00:00Z, I’d like to make a proposal on content reuse from discourse (top posts). If you oppose to it, please come forward and let us know thoughts. Thanks.

I like this idea. Since the migration of Ask Fedora, I don’t think we have thought of a concerted effort of converting top posts into Quick Docs.

1 Like

A success factor of this proposal is;

  • An increase in content conversions of top posts in Ask Fedora that turns into docs PRs from the original commenter or participants. This almost never happens currently, so initiation of content conversion/reuse would be a great indicator of success.
  • Reduction of related posts on similar issues: helpers get stretched out to support similar questions over and over again. We could just share a link to most relevant articles. At the moment, do this and do that…not always that advice resolves issues.
  • Reduction of contributor fatigue: it is hard to measure, but from my real experience, one of top reasons for low morale/job transfer are friction between helpers and requesters.

Let me share a summary of discussions in Docs Matrix room and offer you three options to choose from.

Option 1. Fedora Linux Admin Tools

Link to Repo

Lead mentor (my idea): Peter Boy

Option 2. Content conversions of top posts in Ask Fedora into Docs PRs (Quick Docs)

Lead mentor (I volunteer): Hank Lee. I would expect a minimum of two other mentors to assist me.

Link to pitch deck

Option 3. Sunsetting System Admin Guide and replace it with something else

Link to the guide

Reason 1: It’s based on old RHEL docs and hasn’t been properly updated. Target audience of Sys admin guide is professional users rather than Fedora users.

Reason 2: Although Fedora Linux is known as developer friendly distro, Docs for expert users are under-documented. For system administrators and developers, they often go to family distributions (Red Hat, Rocky Linux, for an example) to get necessary resources.

We don’t have a lead mentor with option 3.

Depending on the option we collectively decide, a lead mentor needs to approximate working hours required to complete the task, suggest what support you need, and how many hours the lead mentor can invest with the mentee(s).

We haven’t got much time to write up the application.

I guess option 1 and 3 are nearly the same. Another option would be sunsetting system admin guide without replacement at all.

Well, in any case, we need a decision soon. I don’t know the details out of my head, but as far as I know we have to submit the project at latest Apr 2, Tuesday next week.

We have a more or less complete text for option 2 and a somewhat indecisive discussion for option 1 or/and 3 (although we had already discussed this around 1 1/2 years previously, albeit in a different grouping). Therefore, option 2 seems to me to be the better alternative in this situation.

This would also give us the opportunity to reconsider where we want to transfer the Administrator’s Guide. Another possible target would be Quick Docs. Due to a quality debate with our intern a good year ago ( @likeanushkaa ), we decided against it. However, if we could manage the planned conversion of Quick Docs to categorization and tags instead of a navigation bar, this would mean a new situation for a possible target. And that would be another argument for choosing option 2 now.

In any case, we need a decision today ( Mar 29) or tomorrow. Further feedback is welcome.

That’s not a bad idea.

If previous discussions were meant to develop Fedora Linux Admin Tools (option 1), we could have a parallel discussion, apart from the Google program application. Intended user group and complexity level for such guide should be validated by the broader community members.

It’s probably time to discard the term “Fedora Administrator’s Guide” as a target. We explicitly discarded this term more than a year ago for the same reasons we discarded the “Fedora Installation Guide”. Such a guide no longer makes sense and is no longer possible at all. There is no longer a unified Fedora distribution, but Fedora is differentiated into specialized editions – although these are of course based on a common basis. And because of the shared bases, we still have “Fedora Tools” for administration and maintenance. Examples are kernel installation, various kernel utilities, dbus, systemd, dnf, rpm, … These need documentation, which will usually be somewhat longer. This type of documentation is not suitable for Quick Docs.

So there will no longer be a “Fedora Administrator’s Guide”, but there will be a documentation of the “Fedora Tools” for maintaining the system.

I don’t mind the term to retire as it doesn’t fit the purpose. I’ll leave it up to you and Petr to take actions.

In the meantime, the new term “Fedora Tools” sounds vague, asking for explanations. Some of those you mentioned are adopted by other distros beyond rpm-based Fedora families. Is it still correct to call it Fedora tools (as the upstream source)?

I understand the rationale.

Could you open a new thread so this is not mixed up with original thread?

I will do that when we have someone to contribute work to it. That may take some time.