Please let us know: How to improve the guide for casual contributions in Docs? Which possibilities in the new GitLab suit you best?

Project Discussion
1

Hi all,
Based upon previous discussions, you may know that we created a guide for casual contributors, to lower the entry barrier to contributions in our Docs, and especially to enable people without connections to git to contribute without much efforts.

However, originally identified by @sampsonf , the user interface of GitLab has changed a lot, and thus, it can be questioned if the original goals of the guide can still be achieved, if the original target audience is still realistic, and even if so, how to achieve the goals to enable the original target audience to contribute easily.

This is why we ask the people who use such a guide: how to proceed?

Generally, if you are interested in any way to contribute to the Docs, even if only on a casual basis, you are right here and your incentives in any direction are welcome! This topic is for you.

Please feel free to let us know about your thoughts and incentives for any of the following questions but also complementary ideas (with regards to the discussions of here and here, but also the original discussions of 2021/22 that led to the concept of the guide):

  1. With the current GitLab user interface, are you interested at all to keep using it for casual contributions?
  2. If yes, are you interested to only get your contribution done as quick and as simple as possible without being bothered by “why is it the way it is”, or do you want to get some understanding about git or to even start implementing its best practices, even if it adds some steps? An example for the latter would be to create and use your own branches, as you can see it currently in the guide.
  3. Based upon the current guide, do you have any general suggestions or needs?
  4. Currently, we have identified the following possibilities - which would you prefer?
    → each time remove the old fork - maybe easiest because it does not need much understanding, but it maybe feels a little destructive and does avoid to deepen understanding of git
    → if your fork branch is not up to date, you can see it, and we can tell you how to update - definitely the best practice, but might be confusing and deterring for people who are not interested in getting deep into git
    → Please try to find a way to avoid forking and such at all because the above means take too much time or for other reasons so that I cannot contribute that way.
  5. With regards to the 4th question, do you maybe have other ideas or thoughts about how to tailor the casual contribution process and its guide in GitLab to satisfy your demand?
  6. Anything else you have in mind! Do we maybe ask the wrong questions? We are open to everything :slight_smile: The only limit that we have to set at the moment is git: too many of Fedora’s Special Interest Groups and Working Groups depend on the use of git when maintaining their respective Docs, directly or indirectly.

The underlying questions for us are: who is the current (realistic) target audience? What is their demand? How to achieve satisfying this demand?

There have been changes both in GitLab and maybe also in the audience that uses this guide, whereas the latter might be influenced by the first (obviously, one related question is if it is even possible to create a GitLab-based process that is interesting for people without git-preferences). So, here we go, let us know :slight_smile:

Many thanks to @hankuoffroad who took the initiative to start adjusting the guide to changed demands and to reveal that we have to also re-consider the targeted audience.

Supplement: concerning the questions, it might be complementary to check out the links provided by Hank in his post and his additions in the second.

Looking forward to your thoughts,
Chris

1 Like
2

As a point of reference, please find the first release made by @py0xc3 and a revised version.

Before: Fedora Docs "HowTo" for casual contributions :: Fedora Docs Staging

After: How to make casual contributions :: Fedora Docs

2 Likes
3

@py0xc3 we also need to consider how contributors find tasks and how we expect users to authenticate.

Find tasks

Recommended user journey was to click edit this page (tiny button) in GitLab.

As the new website 3.0 is live, user journey needs to be evolved from it.

Easyfix is under Contributors category on top right.

Contributors > New Contributors > Easy Fix

https://fedoraproject.org/wiki/Easyfix

Authentication and permission

Do we expect everyone to link the FAS account? If they are external users, what will they benefit from? I think this could be one of ‘incentives’ @py0xc3 refers to.

It needs to be clear from the start of the process, so users get the same experience as the guide explains.

GitLab introduced credit card verification process to block spam users. If not verified, users get super-annoying pipeline error when MR is made. Say ‘just ignore it’?

For people who are inexperienced with Git and dev process, ‘pipeline’ error scare them off miles away.

FYI, in Pagure, there is ‘temporary membership category’.

4

@hankuoffroad thanks for the points! I added your posts to the topic so that people can consider it!

However, I suggest to first focus on GitLab, which is likely to cover the majority of what people might casually contribute to. Since the Quick Docs remain in pagure, it makes sense to also develop a guide for pagure in future. But I don’t think we can merge both into one guide. Btw, darknao already noted earlier that it is no problem that users get automatically forwarded on our Docs pages to the respectively correct guide. So if we have one for pagure and one for gitlab, they would click the button on the respective page they want to change, and then get forwarded to the applicable guide without needing to know themselves which they need.

When it comes to errors and such, my suggestion would remain to let users know what they can ignore/neglect as long as the MR gets submitted (or add a link to GitLab Docs if they want to get deeper?). I would argue that everything else would end up in something comparable to the existing GitLab Docs, and be likewise interrelated/complex. But that might be linked to the above questions about which contributors expect what from the guide (audience & its demand). Therefore, my suggestion is based on assumptions that can be questioned.

5

There are existing QuickDocs guides published in March and they will serve users separately.

The only reason I mention other repos (I know it will confuse new users) is there is no reason why the process varies too much for GitLab. I’m not suggesting all guides to be one consolidated version.

For a person like me who is peeking in all three repo hosting sites, any significant process variance does not really make sense. That’s all. I’ll leave these to real users and try to stay neutral (me being a beta tester).

6

Adding another one,

Live preview

One of most expected features for editing AsciiDoc is side by side view with rendered page (Live preview). I think it is natural for people who are used to WYSIWYG editor that comes with Markdown or wiki/blogging platform.

‘View app’ is recommended after MR is made to run live preview.

Syntax highlighter

Current Web IDE doesn’t have syntax highlighter as a default on editor pane. You need to install AsciDoc extension, which is blocked in beta.

7

Please bare with me as my English is not good and my writing is un-organized and hard to follow.

A. Too many places where Fedora Docs are being hosted

  • different sites need different knowledge to get involved
  • even for just reading the Docs, need more understanding to know which version/site should be followed for a particular topic.
  • Not sure if a mass / batch import is possible. Just consolidate into one site. And involve the wider community to help find out which is the latest version to use.
  • One site, same way to get involved to all Docs.

B. Different level of involvment

  • I definitely can only try to do casual contributions
  • How I define Casual contributors
  • To flag trival points regarding existing Docs: spellings, Current (still applies for which version of Fedora), Outdated (no longer apply to “Supported versions” of Fedora)
  • Add/update screen shots, etc.
  • Without deep understanding of the workflow / tools involved: Create account at multiple systems before able to contribute. While each system require dedicated HowTos to setup correctly ; need to know which place is correct to ask questions about different topics
  • Feel welcomed: how much help is readily available for those cannot follow existing instructions?

C. It might be helpful to me (not sure if my need is typical or not)

  • An overview of the current Docs site situation. Like how many different sites are commonly visited by users (by Search results? by being mentioned in other Docs, Website links, etc)
  • Which Contribution GetStart guide is available for each site
  • If a particula site allows Reader to give feedback while reading it, show it clearly which Contribution guide should be followed. And where to get help with the tools to use.

D. To be feel accepted

  • Do not want inputs to be ignored - even a reject result is a good result.

E. Not everyone is an all rounder

  • Docs Readers will very likely to flag issues of existing docs
  • Editors knowing enough can create Merge Request in the correct format, at the correct place to get the flagged issues update into the docs
  • Someone might be able to identify which topic is in high demand, and invite writers to write about that topic
  • Someone can help to organize the available Docs in a good way, so it can reach more readers / contributors, and have bigger impact.
  • Someone can help new comers to be a better contributor

Back to your specific questions:

  1. If that is the only way to contribute, and will not be changed in short term, so be it. Personally, I will only try to do as far as I can learn to use the tool. Without enough positive feedback, I will try harder to learn about the tool, naturally.

  2. Task based instructions

  • How to submit a Spelling error
  • How to submit a new Screen Shot
  • How to flag applicable versions
    (I know in this way, the Instructions will not lots of duplications - but for me, need to read multiple linked sub-doc to do the most simple suggestion is too complex)
  • An essential guide to GitLab will help for those want to become more advanced contributor
  • Explan the commonly used feature of GL applicable to Docs
  • Explan the essential GL/git concepts necessary to Docs
  • As long as there is a way to override this for those in need, remove old fork for the beginers. And help those need to maintan a fork.
  • Create a “Docs” category in ASK
  • Posting here, means allowing anyone to convert it into Fedora Docs
  • Encourage people (including the original topic owner) to update the docs based on the good contents

My hope is, as a Fedora user, I only need to read Fedora Docs and Upstream Docs, and visiting ASK in order to use Fedora.

1 Like
8

Thank you very much for your incentives! A lot to consider.

I will work through your points in the coming days.

However, unfortunately, I can already say that centralizing the hosting
of “git repositories” at one service will be not possible because there
are different teams that maintain different “git repositories” of Docs,
and they work with different git services at the moment (gitlab, pagure,
github).

Given the nature of Docs, most teams that develop/maintain any Fedora
edition/spin (or other stuff) but also many of our SIG/WG are somehow
involved in maintaining Docs related repositories, and they have their
own preferences based upon their needs.

2 Likes
9

@sampsonf @py0xc3

A quick list I put together is here. Pick one project (product) of your interest and expertise and get used to repo structure and types of issues and PR/MR merged.

Project by Git hosting services

Authoring tool

  • Web IDE (VS Code): GitLab, GitHub
  • Local authoring environment and build script: GitLab, Pagure, GitHub
  • Built-in editor (need write access to upstream repo): GitLab, Pagure, GitHub

Whatever tool you pick up and get used to, the process can be translated to other repos. You don’t have to relearn everything.

Role-based tasks and skill development

Refer to the latest Docs pages (one with revision date and standard AsciiDoc template) to adopt best practice. You need to do research and test documentation with build & preview script in some cases.

10

If you need definition on ‘casual contributions’, please check this 2020 FOSS contributor survey by the Linux Foundation.

‘Casual’ (known as occasional) does not relate to complexity of tasks. It is rather time allocation (frequency and commitment) factor. Ironically, on this survey, time allocation of occasional contributors is more than maintainers/core contributors.

Motivation and willingness to learn are something existing members and experienced colleagues can inspire for new and casual contributors. We need to instil ‘self-starter’ mindset and meritocracy.

1 Like
11

By searching the report, there is no “Casual”, and 20 “Occasional”.

Casual contributions and Occasional contributors are two different entities.

In my mind, I am thinking more about Casual Contributors, which can make frequent contributions in the correct situation.

12

Well, without going to much of semantics, two terms are closely related to time, not complexity. First-timers are often thought to be casual, but I don’t see that (ill-informed) convention in any of publication.

Casual contributions are far from being trivial.

Personal needs was the most reported motivation for the casual contributors, who claim that lack of time is a reason for not becoming more active.

Definitions aside, what I evidenced from various feedback in Discussion appears to be;

  • Could be easier to find resources than now
  • Expect better onboading and quicker first contribution from joining
  • Feedback to your contribution rather than radio silence

You can try a small thing and experiment it first all in GitLab. I felt relieved when I learned how to use live preview in GitLab UI because I am certain how the page will look like, predictably.

Images

First, try replacing outdated UI images.

  • Style guide - images and screenshots
  • Check the latest template in source file used to understand image macro: You also need to try ‘view app’ for live preview to make sure your update is rendered correctly.

Feedback

  • Learn MR process and template: what structure is used and check merged MR
  • Ask a reply on your first MR if you don’t hear from reviewers over 3 days. Be patient and check progress.

Things I like about GitLab

  • Another bonus was I didn’t need to type GIt commands over and over again. It is commit & push - one click in Web IDE.
  • Web IDE (VS Code) isn’t necessarily documentation tool. But regardless of hesitation among developers in GitLab, I would say ‘why not?’
1 Like
13

@sampsonf @hankuoffroad I think we develop off-topic and away from our goals in this topic.

Generally, we are not required to follow any rigid definition of casual contributors. We have to find out ourselves what fits us. And with the people who use our tools for casual contributors, the definition may develop. I am not sure if it is necessary or even constructive to permanently “fix the one definition”.

In my opinion, one of the issues we have is to find a new definition to start with in order to derive a target audience (I elaborated that a little in the topic post).

Hanku already added points to the guide to help people to get deeper into git, and to get deeper understanding, which develops the definition: our past definitions were based on people who just wanted to get their contribution done without being bothered by git, because not everyone needs git, and investing time to really understand git only to make casual contributions can be questioned in its sense.

However, given the evolvement of GitLab, I am not sure if the past definitions still fit our needs, because it can be questioned at all if it is still realistic for the “originally derived” target audience to do casual contributions: getting basic understanding of GitLab (and thus git) seems not avoidable on the long term. And at the moment, GitLab seems to develop their functions further faster than we can identify and tackle issues that rise from it when it comes to our use cases (which can be deterring and annoying for contributors).

So maybe the new definition to start with is people who casually contribute without being permanent member and without taking long-term responsibility but who remain with contributing irregular once they find some issue in the Docs they can solve off the cuff. Additionally, and this is the major difference to the past definition, we are talking of people who want to exploit their “casual contribution” to get some basics of git, which means use the casual contribution to learn (which also means they invest a little more time than just “click and done”).

Feel free to question every of my points, nothing of that is fixed yet. But we do not need to invest too much time in arguing about definitions: this will be answered by answering the other questions (my goal was to derive definitions/target audience from answering the original questions).

However, with Sampson’s ask.fedora #Docs tag idea in mind: @sampsonf it should be possible to add yourself the #docs tag to any topic you open on ask.fedora. Once any user has created it, it will be in the list there (let me know if this does not work in the merged discourse).

I think it is worth to think of increasing the use of ask.fedora for casuals, making the guide more a point to start, sufficiently generic/abstract to remain reliable, but still giving casuals a sufficient overview of what this is all about, and for questions/issues, we can make a stronger focus on and link to ask.fedora: this has a low entry barrier because every day many people ask “how to achieve this” questions there. Just a thought :slight_smile: Does that make sense?

1 Like
14

That’s clear for me.

15

Chris, I agree to most of your arguments, at least as far as I understand something about things to which it refers. One thingee in particular caught my eye:

“Casual contributor” often comes with “casual GitLab user”. And GitLab in its current user interface is nothing for casual users at all. Maybe we are running after something that is not attainable at all.

Another question is what our casual contributors actually contribute to. If I know the numbers correctly, it’s mainly Quick Docs, so via pagure.io. Maybe we should focus and limit our efforts on a good pagure.io tutorial?

1 Like
16

This is insane…I was thinking in the same vein.

I spend more time in QuickDocs for content improvement such as review with style guides and technical check for the words that are written. Pagure Web UI is serene and fast to get the edit and PR done. No pipeline error.

GitLab shows me lots of potential work beyond actual user content and words. Sure there are rewarding tasks such as web UX work, AsciiDoc attributes, CSS, and design elements to make Docs better.

17

If you mean to flag pages that have issues, we had such a function in mind but it ain’t that easy to implement. So far, the only alternative is to open issue tickets: see the “bug” button on the top right of our pages (the most right button). Sometimes people use it, but it has never been a focus.

However, since GitLab is to become more and more complex and adds more and more steps, I guess for many casual contributors, the “bug” button could become an alternative to forward information more easily and with lower entry barriers.

Other general alternatives are of course to mention issues in our IRC / Matrix channel, or of course here in discourse. Maybe we could also propagate this possibility more on pages?

We try, but especially at the moment, things develop faster than we can respond. And now we have the same issue with GitLab and its UI, which makes the guide a mess in its original approach. But we are aware of this one issue.

This is linked to the last paragraph of my recent post. I like the idea of making more use of ask.fp indeed. It is more resilient to some of the issues we have with our guides/HowTos. But we have to be careful to not blur ask.fedora because its goal is to be differentiated from the project discussions. Yet, both should enable to reach us, and for many ask.fedora is likely to have a lower entry barrier, and technical questions and elaborations are in the scope of ask.fedora.

Maybe we can have a short discussion in our meeting involving @pboy @hankuoffroad @darknao if we should more actively exploit or propagate the available channels including docs topics in ask.fedora, to forward any type of information with regards to Docs. If we do that, I could pick up the responsibility to have a look on the tag (automatic mailing at specific tags should be possible with discourse). I guess this will not become a game changer, but it is at least a means that we could keep tracking.

When it comes to actively propagating, I think this is a wider question, which is not limited to propagate ask.fp for Docs-related technical questions, but generally propagate our communication channels, which seem to be not obvious. Indeed, at the points most people interact with Docs, there is not much explicit that they can contribute or how (and why) to communicate. I think the “7-step guide button” was a good point to start to make aware, but this guide is no longer suitable for many types of users because of the increasingly complex git steps.

Maybe a link to Matrix, project-discussions and ask.fedora as additional buttons on Docs pages or so? And links and explanations on pages, guides, and so on, about how (and why) to reach us? (footer/header? But we have to be careful to keep the focus on the content, and not add too much other stuff)

It is maybe a little off-topic, but feel free to elaborate what you mean. I have just rejoined after some months of absence, so I am not fully involved in our current pages. But are there particular issues with the current pages? About how to do contributions and such? Maybe your incentives here are most relevant for @pboy and @hankuoffroad , I think they are working on the pages that aim to be the point of arrival for newcomers (feel free to correct me : )

Definitely a perception we have to tackle. We try to be available in all channels. Matrix, discourse, GitLab. My perception was that we tackle what comes up. But I think this issue is related to the previous one about propagating communication channels and such: our channels are not sufficiently obvious at the points where people interact with Docs.

Unfortunately, I do not understand that point. Can you elaborate?

I try to work through your remaining comments in the next days :slight_smile: But thank you already for your incentives!

18

Yes, indeed. I think we have reached this point. And GitLab seems to not develop into a direction that makes it better for our use case.

Interesting. I did not know that. But I think we should first evaluate if the issues of GitLab also apply to pagure, which is linked to the question of the target audience (e.g., are only git people capable to manage that? How much efforts and steps are necessary? And does the remaining audience need a guide?).

I am not used to pagure, so I cannot help much here. My perception was always that it is more focused on people working with their git cli with the GUI being more a second line (?).

19

In general, yes. But, e.g. using the issue button to create an issue, is much easier than with GitLab. You have just muss less options, the GUI is much clearer and not nearly as cluttered. And the WEB UI is limited to just edit one page. And even here there are fewer options, the GUI is more concise and everything is not so cluttered.

20

Considering limited resources we have in Docs, I am in favour of self-serve options like contributor guides (needs more improvement). If contributors still can’t find right resources and want to ask a question on IRC/Matrix, Discussion, then you can send the link.

Adding another type of tags for Ask will take time for people to use and requires an update to our documentation. I’m not in favour of adding Ask tag.

We need to guide a well-known signpost for FOSS contributors and essential resources whatever project it is.

  • README.md file on Docs repo
  • Contributor guides
  • Style guides
  • Onboarding guide: concise and easy to follow