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

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.

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:

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.

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.

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

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”.


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.

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

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?

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?

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.

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.

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.