Improve "Tutorial: Make a GitLab contribution"
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Problem to solve
Dear team, this is my first issue within GitLab, so please bear with me if it turns out I approached it in a non-standard way.
I wanted to see how I could contribute, so I rejoiced upon finding out there's a Tutorial. However, as I tried following along, I started to feel ambiguity and unclarity regarding what it's suggesting to do.
In this issue, I'll try mentioning some specific points to make the problem more actionable, but most likely the points are not exhaustive and a ground-up overhaul of the tutorial might be beneficial - I'll welcome your inputs about if you think that might be the case.
Also, I was thinking if it is possible to understand how many people actually successfully managed to finish the tutorial compared to the number of people who started reading it, i.e. the "onboarding funnel" of sorts.
Further details
- the tutorial mentions "As this text has already been changed when developing this tutorial, you can instead search for Customize the appearance of the syntax to find the files that were changed.", but does not suggest what could be changed in the new variant, rendering the whole intention of the tutorial rather ambiguous, at least from my point of view as a first-time contributor. If the text is already changed, what should I be changing it to - revert it to the previous, unwanted variant maybe? Or coming up with some wording on my own? I'm afraid that's already too many open questions to deter from continuing the tutorial. From my experience when following guides and tutorials, those are moments when the person is trying to navigate a lot of unknowns, with the tutorial being often the only known to rely upon. This is also why I suggested above that it might be good to overhaul the whole tutorial: with keeping this perspective in mind, to keep the instructions as clear and unambiguous as possible, removing space for uncertainty.
- the bullet point mentioning "Search the gitlab-development-kit/gitlab directory for the string This setting allows you to customize.
The results show one .haml file, two .md files, one .pot file, and several .po files." - there seem to be >70 .po files, which makes me as the first-time contributor think that I would probably need to alter all of them, if I change the argument passed to
s_in theshow.html.hamlfile - and the linked example MR does not show those files as changed, which might indicate that those were introduced later than that MR. If those are irrelevant and don't need to be changed, the tutorial should explicitly mention that.- also, the tutorial does not address the fact that the text in question is wrapped in a
s_function call - I think it could be good to encourage the first-time contributor that translations like this one are indeed changed both in-place and in the catalogue (.po / .pot) files, ideally offering a link to a doc what GitLab's conventions regarding translations are. A link to Internationalization is mentioned in a latter section, however it contains possibly too much information for a first-time contributor to understand, moreover IMO it would be great to mention it sooner, because the contributor encounters thes_call in the first section already and it might not be obvious that it will be answered in the latter section.
- also, the tutorial does not address the fact that the text in question is wrapped in a
- the bullet point "Refresh the web browser where you’re viewing the GDK." assumes I already am authenticated in the GDK. But that's not the case: at least when following the Gitpod-based setup, the first screen opened is
users/sign_in. It would be great to add a few words about how to register, or if there are some fixture accounts available, maybe each of them with different features enabled. Also, if there is a mailcatcher service enabled and how it can be interacted with, or if I should expect the registration confirmation mail to arrive to my real mailbox. This is relevant all the more because upon registering, the flash message "You have signed up successfully. However, we could not sign you in because your account is awaiting approval from your GitLab administrator." appears. - the bullet point "Go to this location in your local gitlab repository and update the .md file and any related images." does not explain what updates should be made to the .md file
- the whole "Step 4: Create a merge request" further invites the question of the goal of the tutorial, which I already mentioned in my first bullet point of the "Further details" section. If each first-time contributor is doing this change, what will happen next? Will the MR ultimately be cancelled, because there's no point in having 10s of MRs changing the text back and forth? Some brief explanation of this flow would IMO be great to have already in the very beginning of the tutorial, something like "Throughout this tutorial, we'll be creating a MR which the GitLab bot will ultimately close, because this is just a test change. If we merged your change, it would make the instructions in this tutorial non-applicable for future first-time contributors, thank you for your understanding." maybe.
Proposal
As suggested above, I think it might be good to rethink the tutorial, possibly with some validation with actual first-time contributors if that is feasible.
I want to emphasize I really value the intention of a first-time contribution tutorial, it's a great idea and I really believe it might go a long way in making the first-time contributors feel welcome. I hope my suggestions will help improve it further.