The "How to make casual contributions" guide: what do you think? how to improve? how to tailor? (and for whom?)

Project Discussion
1

@hankuoffroad since there are several discussions, tickets and Matrix conversations about the “How to make casual contributions” guide, I open a topic here to get some consolidation and some possibilities for an “overall discussion” but also for external incentives.

For the community, we were looking for some incentives about how and where to improve the guide, and where issues are in terms of comprehensibility. Any incentive is appreciated. @hankuoffroad already updated the guide to more current needs and introduced a more appropriate approach because the last approach does no longer fit the current GitLab UI. However, we still lack feedback from people who actually use the guide, and for whom the guide is finally intended for, which also leads to the question of who/if the audience is, and how to tailor to/reach them (the audience discussion is interrelated with a parallel discussion, see the link below).

The guide: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-gitlab-howto/

The recent update: a) Contributor guide update for GitLab documentation (!91) · Merge requests · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab
b) Style change (!92) · Merge requests · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab

Related discussion that refers to the role of the guide and its potential audience: How to PASSIVELY let users know THAT and WHAT they can contribute?

Obviously, audience and content are related (the later might be tailored to the first).

2

@hankuoffroad I wanted to give you some more detailed feedback since our discussion, but my schedule remains filled. However, two initial points I had in mind during my “rough skim”:

What was confusing a little are the “bullet point” steps that are subordinated to the actual steps, especially in conjunction with each other. So there are the superordinated “steps 1” and “steps 2” and so on, which are clear: they are all to be implemented subsequently.

However, several steps contain further “sub-steps” that are structured as bullet points. The issue is that for me it is sometimes not clear IF all these bullet points are to be implemented OR just one OR some, and IF they are to be implemented subsequently OR without specific order.

Maybe the bullet points can be introduced by a tailored sentence like, e.g., “conduct all the following bullet points in the given order” or “conduct the one applicable bullet point”, and so on (just illustrative examples). Or alternatively, use 1) 2) 3) instead of the “bullet point” dots or so?

Generally, having the many sub-step structures resolved into the superordinated step structure (so to have only one step structure without sub-structures) might be most comprehensible, but I assume that this needs to invest more time than we have. I guess this links to the discussion about resolving the different contributions and different approaches that are currently contained in the guide into a “common approach”. However, resolving the sub-structures could make it harder to maintain the guide, but here we would need to know from the audience that actually uses the guide if the sub-structures are sufficiently comprehensible. (Which leads to …)

Maybe a point in the beginning (a caution box with link or so) about that we seek feedback and knowledge about the audience, complemented by a link to provide easy feedback without login or so, might be helpful to get the incentives (e.g., use hackMD or etherpad something like that, things that do not need any login or so) so that any user gets an immediate incentive to quickly and easily give some simple feedback when they just opened the guide. I think it is important to focus on if/who the audience is against which we have to tailor to.

However, your changes are definitely a strong improvement compared to the earlier versions, especially with regards to the changed environment of GitLab. It would be cool if we can manifest your new approach in cooperation with users to tailor and implement it throughout the page.

3

That’s a lot to take in. The discussion needs to be current so that no one is trying to remember who or what was involved.

Some of your reflection is not in sync with actual work I put into it.

There are possibilities for improvement - feel free to improve on it if you like.

Important to get user feedback, so could you give some space until users come back with suggestions? I have no time and energy to dwell on one thing too long. Please be more patient with potential users.

4

I think, given our scarce resources, we can’t avoid taking smaller steps and focusing on immediate needs. The most requested documentation that we as a Docs team are responsible for is Quick Docs. And Quick Docs is on Pagure. By far, the most requested installation media is Workstation and Server. Both of those documentations are also on Pagure. This suggests that we should focus on writing documentation for Pagure.

Pagure offers a web editor for a single repo document. The alternative is the local Fedora authoring environment. I think it would be smart if we focused primarily on these two documentaries.

If possible, we should in a first step postpone the broader perspectives until we have solved the urgent problems. Of course, in a subsequent round we then have to discuss and solve the more general questions.

As a next step, we could ask new users to try the guide and improve a Quick Docs article.

Just an idea.

5

That is indeed a valuable point I have missed. Indeed, the focus should be on pagure.

We have to keep in mind that sometimes current approaches are the reason for the absence of change. So the short term steps might be the reason for resources remaining scarce (the outcome of an approach remains always the same if the context does not change). This argument is of course not very relevant here, but we have to keep it in general in mind when deciding how to proceed.

Indeed, maybe the interest to collaborate is higher on pagure. More people, and especially the Quick Docs have also a wider audience. Unfortunately, my expertise in Pagure is limited, and my time to get into its web UI and write a new guide as well. However, I guess I am myself a good candidate to test the Pagure guide if someone has time. If anyone picks up the Pagure guide, feel free to let me know: I can test its drafts (also interim rudiments and such if that helps) and see if they help me to get into Pagure more easily :slight_smile:

6

Yeah, agreed. We have to make sure that we don’t just do the minimum routine tasks, but also systematically keep working on adaptation and innovation. This is a matter of systematically designing our agenda and work plan.

7

Articles on ‘How to contribute to Quick Docs’ are linked to readme file of the repo.

I think Peter refers to improvement of Quick Docs articles (about 90 files) rather than the contributor guides.

I copied and pasted a section of README file on the repo.

New content creation and curation

Please refer to the guide from the links below.

If you’re interested, I can show you how I work on documentation in Pagure. I like local preview when making substantial editing.

8

Yeah, ‘unfortunately’ both are interwoven. We need to improve the Quick Docs articles, but to be able to do we need contributors guides. And we need to onboard new contributors. That’s why your work is so important.

And thanks for the update of the README! That is another area that has been lying fallow for a long time and so is not exactly helping to achieve clarity.

1 Like
9

On contributor guides, we need to spare some time to;

  • How to edit partials: Started as good intention as content reuse, partials are deterrent to new comers. After a round of commits, new comers fall out on complex notation of partials.
  • Update issues in EasyFix: This is now listed in new contributor menu in the website 3.0. Issues on EasyFix could be linked to ‘Good first issue’ labels.
  • PR/MR review timeline: 2 to 7 days are noted on the various contributor guide. I often see this is not the case. When no one is responding to the first PR of new comers over 1 month contrary to the guides, I think we are telling the contributor the repo is not maintained.

Having more contributors is easy. Keeping and nurturing them is not helped by contributor guide alone. Please think about balance of time and efforts.