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
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
21

Now the question is what kind of documentation contributions you want to make, not tool or Git hosting services.

If technical documentation (how-to guide, tutorial), QuickDocs is the way to go. There are various topics that you will find a good match and interest.

22

Concerning ask tag: On ask.fedora, everyone can use and add any tag.
Tags are not limited there like in other categories. This is
intentional. At the moment, the Docs tag does not exist only because no
one has yet opened a topic and added “Docs” or “Doc” as tag. But over
time, it is possible that both tags will rise: if the tags exist or not
is not in our responsibility/power. We can only control if we monitor
and/or respond to ask-topics that are tagged #doc or #docs. Just to
avoid misunderstandings :slight_smile:

23

I meant to say I have no bandwidth to take care of those questions in Ask/Discussion. I would rather dedicate my time to improve technical documentation, user journey in the website, and review PR.

24

To be honest, I am not sure if such a HowTo guide makes sense at all at the moment: As @pboy named it, we have “casual git contributors” at the moment, not other “casual contributors”. The first do not need such a guide I guess, while I do not think that we are able to provide something acceptable to the latter.

I do not know if it is different with pagure (are only git people capable to manage that? How much efforts and steps are necessary? And does the remaining/resulting audience need a guide?) → maybe it is generally worth to review the people who do casual contributions on pagure?

We had a time where some “non-git” people started to casually contribute (never a major share), but now it has become very complicated again. So if things keep developing as they do on related user interfaces, I doubt at the moment the need for a guide that we would be able to provide.

So the question is also about if there are other means than guides and tutorials? The casual contribution guide serves currently the most with letting people know that this type of contribution is possible and appreciated (which is indeed already valuable information). But its complexity might develop more to a deterring factor against the Docs. So the question is if we can put other means at the places where people interact with Docs: means that are maybe more suitable for any audience
that visits Docs pages and that could be interested in contributions.

I had that in mind when reading and answering to Sampson’s comments. So I am thinking if it makes sense to use the “guide”-related space and buttons on the Docs pages (=where people get in touch with Docs) not for guides but for other information: when being on a Docs page, we have to answer potential newcomers/contributors: why, where and how to reach us OR to contribute (“why” is always the critical)

The many pages for newcomers and such are problematic, not because of their content, but because they assume that people are already actively seeking involvement in the Docs, which implies interest, which implies to know that there are possibilities and to have incentives about what types of possibilities (this should not be presumed). However, especially the “why” question might be more linked to the type of information you and @pboy prepare on the related pages than linked to some guides.

I don’t think that this increases work for us if we enable all possible channels. I would say it decreases it, because we do not need to maintain the channels (and “incentives” that lead into our channels) the way we have to maintain guides. If that would not work out, it would not create any work anyway.

However, so far these are just some thoughts for consideration. I am not yet sufficiently deep involved again to derive something, and thus I hold back with explicit recommendations.

25

6 posts were split to a new topic: How to do PR with Pagure for Docs

26

As now Discussion and ASK is merged, if ASK should not be used, how about create it under Discussion?

No matter on which channel I starts, I am looking for:

  • I got the issue (that driving me to start) resolved
  • I will not hesitate to re-visit (needed or not needed)

After a few re-visit, a good out come for me will be, I know what other channel I can use, which will be better for my need, or for the bigger community.

While trying with the new channel, if I am not capable of using it effectively, then I will fall back to “previous level”.

Thus:

This, my thought is, someone frequent to a particular channel, can help new visitors settle down. And slowly, that new visitor might “clip up the ladder” and become an “all rounder” .

Sometimes, I thought I have “submited” an edit. Then the edit got no feedback - either rejected as not good enough, or already “published”, or “need more detail”.

For the majority of time, it is due to myself not understand the process / tools enough, and actually the “edit is done” but “not submitted” .

Thank you.

27

The pages habe been merged, but “Project Discussion” and “Ask Fedora” are still two different categories you see on the left side when you are on the main page. However, you can still go to ask.fedoraproject.org which will automatically forward you to the category.

Generally, whenever you have any question, open where it makes most sense for you. We have never taken it seriously if people accidentally opened a topic at the less intended of our categories.

The point we have to be careful is when we actively propagate any of the two categories for a specific use case: we have to not actively propagate ask.fedora for something it is not intended for.

… but this is an example of what imho clearly falls in the scope of ask.fedora. And if a user who is used to ask questions at ask.fedora if they need help (which is the majority), I would be happy to forward or answer it there.

In this case, this question might be more in the scope of @pboy and @hankuoffroad as they are better specialists of pagure than me :wink: Indeed, your points seem to be indicative about what information users need for the Quick Docs / Pagure and how to improve related documentation/guidance.

I’ll try in the next days to get automatically mailed if someone opens an ask.fedora topic with #docs or #doc just to ensure it does not get lost. Passively monitoring doesn’t hurt :slight_smile:

Thank you for this incentive! I did not see this perspective, but I understand it.

28

So the question is also about if there are other means than guides and tutorials?

Definitions aside, I don’t understand your point here. It reads like how-to guides are not necessary for users. I must be mistaken. What priority is there if I overlooked it?

I’m talking about what documentation casual contributors can help with. What content category do you feel dismissive of?

29

Hello Chris, for the love of humanity and economy of words, could you please be absolutely brief about what concern do you have about the debate we have? We all have a life to live and can’t afford to debate to hell wasting people’s attention in Discussion.

Are we on track to discuss the topic on title?

Please let us know: How to improve the guide for casual contributions in Docs?

I think I jumped on to end goals too quickly - what guide contributors need to produce whereas the original goal was a well-targeted guide on how to contribute for Docs.

Sampson already shared detailed feedback where we could improve. Is there anything else to add here?

30

The goal of this topic is not to collect feedback in order to leave it unconsidered. The goal is to analyze it and to derive and discuss lessons, alternatives and approaches. Some of the comments from Sampson and also from Peter (also from the other topics) to which I agree lead to the question if we shall go one step back, and ask if the GitLab HowTo (or its approach) is a proper means in the changed circumstances.

Generally, it is good practice to collect what you have to say in one post (this is why discourse blocks multiple subsequent posts at some point). This is for better overview, linking and indexing. If there are many points I have to answer (and I already excluded several to limit the post for now), the post will become longer.

I do not consider these comments offensive or so, but because this is a inter-cultural forum where many different social and geographical cultures come together, I suggest to avoid this type of “casually speaking”/vernacular: it can be easily misinterpreted / misunderstood. You cannot control which “cultural/social values” will “filter” your posts.

31

Fair enough on the side of caution.

Back to the heart of matter is about long post.

We could strike a balance between search efficiency and breaking down topics to bite-sized messages considering readability.

I saw a friendly reminder from Discourse to combine a few posts. But, I prefer bite-sized message to long posts.

Actual topic was my previous question on the distinction between how-to / tutorial for Fedora Linux users (technical content like GRUB, custom kernels, nested virtualization) and GitLab contributor guide (this thread). You suggested alternative content type for GitLab contributor guide.

Also about your careful approach on analysis, discussion, approaches, we could try small and fail fast and reiterate for an update and seek a better approach (change its course).

Point of interaction and why-how-what

This could a separate thread, but up to you until we bring the idea into fruition.

We have seen various ideas on how to bring people to Docs and why. So let’s chat more about possible directions and pros/cons over next weeks. Thanks.

32

Hello Sampson, how are you doing?

You already provide feedback on the Docs contributions, thanks.

One more thing I would like to hear from you is the topic on this thread ‘how to improve the guide for casual contributions’.

  • Have you recently used the Web IDE and if yes, how was your experience?
  • Did you follow through the guide?
  • If you’re stuck halfway through and found anything unclear, could you explain your problem?
  • If there are more suggestions, please share. Your feedback will help improve the guide that fits to contributors.
3 Likes