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.
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.
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.
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.
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.
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.
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?’
@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 Does that make sense?
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?
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.
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 But thank you already for your incentives!
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 (?).
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.
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.
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
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.
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” .
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 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
Thank you for this incentive! I did not see this perspective, but I understand it.
Does that make sense?
Indeed, your points seem to be indicative about what information users need for the Quick Docs / Pagure and how to improve related documentation/guidance.