About two weeks ago, @computersavvy from the ask.Fedora regulars identified an issue in the Docs about Grub and forwarded that information. This brought me to the idea that the people of ask.Fedora could be the prime examples of “sporadic” Docs contributors: so, not people who are persistently active in the Docs, attending meetings and such, but people that occasionally contribute when they identify issues during their activities in ask.Fedora while they also tend to have the knowledge to correct/update Docs. In Docs, we discussed before that this type of contribution is explicitly intended, but we still lack that type of contributor.
So we started a discussion in the ask.Fedora lounge to identify how far there is interest in fostering that and to identify why we lack such contribution. On one hand, the ask.Fedora regulars and leaders can give indication about the “why is there a lack of such contribution”, but on the other hand, if we tailor processes and guides to them, we might facilitate such contribution.
Within the discussion, @computersavvy used the issue he identified and kicked off creating a merge request to find out what problems/questions rise. Other members have started to contribute to that, too; related GitLab pages:
→ Invalid commands in grub documentation (#2) · Issues · fedora / Fedora Docs / Fedora Linux Documentation / Fedora Linux Sysadmin Guide · GitLab
→ Draft: This change is to prevent users from inadvertently changing /boot/efi/EFI/fedora/grub.cfg on newer systems where the grub.cfg resides at /boot/grub2/grub.cfg (!1) · Merge requests · fedora / Fedora Docs / Fedora Linux Documentation / Fedora Linux Sysadmin Guide · GitLab
→ Invalid command updated; see... (!2) · Merge requests · fedora / Fedora Docs / Fedora Linux Documentation / Fedora Linux Sysadmin Guide · GitLab
So what incentives have we already from the discussion and @computersavvy 's MR? (this includes the assumption that ask.fp regulars/leaders are representative “sporadic” Docs contributors)
- they know in advance git, how to clone and how to use/get what is already on git, but have no previous experiences in how to work on git, make changes, MR/PR, relating issues, etc.
→ so far nothing new (partly resembles what @pboy or @bcotton mentioned before I think)
→ a HowTo might also include how to link issues and MR; and have a stronger focus on images instead of texts.
→ the differences of branches might be noted to avoid confusion. - not only changes in git in general are a problem, but also our git structures: when on a Docs page, it is hard to identify where to find the corresponding git because our structures can be confusing, especially without preceding experience: it is not obvious to external people that they only have to click a button to end up at the correct repo’s issue or edit creating page.
→ the buttons need to be more obvious, and somehow make it clear to the people that they do not need to identify git repos or so: “click here to directly end up at the corresponding edit page” or “click here if you only want to create a ticket”.
→ Some incentives that they cannot break a Docs page as the MR will be reviewed before merge might make sense as well. This may also be a deterrent.
→ The big issue we have to tackle here is not to explain everything properly in a HowTo guide, but to avoid that people are deterred before they end up at the guide.
→ a short guide may be added as fourth button? Given the incentives from @computersavvy , the immediate information he needed was just a few images and a short explanations.
-
@ankursinha noted that many people assume they have to get deep into git in order to make changes. This is another deterrent factor. It is important that potential contributors know that everything can be done in a GUI of the web browser.
→ in here, it has also to be avoided that the contributor gets confused by the need to make a fork. - this is related to the first point: even if people have already used/cloned data from git, the differences among branches are not obvious.
→ the buttons on Docs pages seem to refer to the respective Fedora version branch such as F36. This is important to us because external contributions need to be shifted to the “main” branch separately if they shall persist in future Fedora versions.
→ I have not yet identified why @computersavvy ended up in the main branch with his MR. As noted above, we have to avoid confusion about the branches. - This is not an issue on itself, but interesting to keep in mind: external contributors (without FAS acc) cannot suggest commits in merge requests, which would have been helpful in our case and more generally in comparable cases. They can only create their own merge requests and create issues (plus comments in both).
The information and images @ankursinha and I needed to put forward in the lounge was:
----------------------@py0xc3
But as “interim answer”: each Docs page has on the top right three buttons you can use to get forwarded to the respective repo:
The left leads to the history of the repo, the middle to the edit, left to creating an issue. As non-Docs member, the edit page will directly contain a button to fork. But in all three cases you are automatically in the corresponding repo.
----------------------@ankursinha
It’s probably also worth adding that one does not need to locally clone files to modify them—they can be done in the browser. Pagure allows this, so does GitHub, and as far as I know, so does GitLab
which takes one to a page like this:
Ankur’s images are not yet for GitLab; in GitLab I would add additionally a dedicated image for the need to fork; and later a dedicated image about merge branch->branch in order to avoid confusion about these two issues. Also explain in short what these branches are, as I did it in the last comment of the first of the MR’s. Also, a dedicated image illustrating why and how to relate tickets with MR might make sense.
So, a general derivation from my side, which we have to consider, is to focus on the Docs pages that are presented to readers and potential contributors, which can facilitate that people do not even consider to contribute (and thus, not consider to check a guide). Plus the individual issues explained above.
→ the Docs page has to make clear in advance how easy it can be, before reading a guide
→ the Docs page might directly have a button for a “minimal” guide which seems on GitLab sufficient (we did not need to provide much information)
We have not yet worked with any HowTo/guide draft, to see how it develops and what is necessary/appropriate.
If we have a HowTo/guide for contributing to Docs, I will put it into the lounge. It seems there is some interest in contributing occasionally if issues are identified on ask.Fedora. The assumption that repos have to be identified first (which indeed would be not easy if it was necessary) and that git has to be used in the traditional way without an easy GUI seemed to be a major entry barrier, deterring people to get deeper into it. I could imagine this deters other potential and highly qualified contributors as well.
What do you think? I could create a draft for such a “minimal” guide and check with ask.Fedora people if that makes sense to them. I suggest to create it with my non-FAS GitLab acc because the published Docs pages also forward to the normal GitLab Login, not FAS, if clicking the “edit” button on a Docs page.
@computersavvy @grumpey @ankursinha @dalto feel free to add further information or correct me 
And thanks for investing time to contribute here!