Helping contributor onboarding with a new website
Hi! A while back, a group of contributors was planning to take care of adapting asknot-ng, a Fedora application powering whatcanidoforfedora.org, for use by the openSUSE Project. That did not happen, so I decided to take it upon myself to get it going. However, I don't know everything that happens within the project, or how much everything within the project works, as much as I would like to, so I need some help with finishing this task. # How does asknot-ng work? asknot-ng works by providing a tree of choices, which it then uses to point people in a direction of things to do within a project. The tree is composed of a few layers of categories (as many as required by the branch) which always results in some link the person can follow to learn more about contributing to a certain part of the project. # How to help out with this task? If you are a person currently responsible for or know how to contribute to something within the project, we would most likely want to include you in this. There are a lot of ways to contribute, and individually we can't know them all, but all together we can find out ways to reach contributors and for the contributors to reach us. If you are just a contributor, that has been interested in contributing to a certain part of the project but couldn't figure it out, we would like to hear from you as well. I'm sure we will not get a full coverage from just the contributors here, so your feedback is essential for us to be able to reach out to the right people we might have not considered. # What are the requirements for inclusion? As you may be aware, some of the stuff that is developed within the openSUSE Project, or closely associated to the project, has guides helping out the new contributors to be able to contribute to it. In some cases that is CONTRIBUTING.md document in the root of a git repo, in others it's a wiki page like How to contribute to Factory, which is likely pretty well known to anyone that has ever pushed anything to Factory. This kind of documentation is something which we would like to help you develop for your branch of contributions, so that other people can help out in a more meaningful way. There are plenty of helpful resources for writing good contributing guides on the internet[1], though a lot of them apply to code and not necessarily to other forms of contributions. Remember that any contributor can be a newcomer, and may not necessarily understand things that may be obvious to you, and may want to use your repository as their learning experience. Explaining how things come together is one of the primary things that have to be written down. Ruby on Rails application repository doesn't look like a Ruby on Rails application repository to somebody who has never seen one, and even when using Weblate, it's easy to get lost when you first get started. For software development, we don't want to link people directly to git repos, because even if they are more familiar with concepts like git, programming languages and have coded before, contribution guides explain how the repo in particular is developed, how to test and run software, and what to consider before creating a pull request. For other forms of contributions, just linking to a homepage is not exactly helpful, we still want to explain how and why to contribute. It's really important to include some form of contact (mailing list, matrix, irc) to the maintainers and developers of the project. Projects not directly under openSUSE, but related to it in significant way (like KDE or GNOME upstreams for example) also count as something we would like to have included. # I have the guide now, how do I include it? If you don't want to mess around with editing yaml files, feel free to create an issue on asknot-ng GitHub page[2] or get in contact with us with methods listed below. If you do want to contribute more directly, there are example yaml files from Fedora side of things already[3], while the openSUSE ones[2] are a little bit empty. The existing content in the openSUSE yaml files is not final, I just wanted to get the website working, so feel free to either add your contribution based on the existing branches, or create a new one. The fact that your project is currently listed doesn't mean it will stay that way then, it may just be a placeholder. If you would like to know our opinion on this before you PR, we have the contact info listed below. Do not worry too much about images, I will likely be going over them later anyway, and will create whatever ends up being required. # Where will this be hosted? Currently the plan is contribute.opensuse.org, I have already submitted an MR to host it on our pinot machine, and it's being reviewed. It will likely come up online in the next couple of days for preview purposes, while we work on adding content. # How do I get in contact with you? There are a few ways: * GitHub issues on asknot-ng repo[2] * #web:opensuse.org on matrix * #web on discord.gg/opensuse * web@lists.opensuse.org mailing list * #opensuse-web on libera.chat [1] https://mozillascience.github.io/working-open-workshop/contributing/ also includes follow up resources [2] https://github.com/openSUSE/asknot-ng [3] https://github.com/fedora-infra/asknot-ng/blob/develop/questions/fedora.yml https://github.com/fedora-infra/asknot-ng/tree/develop/questions/includes/fe... LCP [Jake] https://lcp.world/
On Tue, 2022-08-16 at 12:31 +0200, Jacob Michalskie wrote:
Hi!
A while back, a group of contributors was planning to take care of adapting asknot-ng, a Fedora application powering whatcanidoforfedora.org, for use by the openSUSE Project. That did not happen, so I decided to take it upon myself to get it going. However, I don't know everything that happens within the project, or how much everything within the project works, as much as I would like to, so I need some help with finishing this task.
# How does asknot-ng work?
asknot-ng works by providing a tree of choices, which it then uses to point people in a direction of things to do within a project. The tree is composed of a few layers of categories (as many as required by the branch) which always results in some link the person can follow to learn more about contributing to a certain part of the project.
Just took a look at whatcanidoforfedora.org and I really dislike the way options are presented. The problem is, that you could likely help with more than just one thing the project needs, but the UI/UX makes the guides impossible to properly see and navigate. Have you thought about providing a separate page that just displays all avilable guides in some kind of tree-view (for example a staggered table)?
# How to help out with this task?
If you are a person currently responsible for or know how to contribute to something within the project, we would most likely want to include you in this. There are a lot of ways to contribute, and individually we can't know them all, but all together we can find out ways to reach contributors and for the contributors to reach us.
If you are just a contributor, that has been interested in contributing to a certain part of the project but couldn't figure it out, we would like to hear from you as well. I'm sure we will not get a full coverage from just the contributors here, so your feedback is essential for us to be able to reach out to the right people we might have not considered.
# What are the requirements for inclusion?
As you may be aware, some of the stuff that is developed within the openSUSE Project, or closely associated to the project, has guides helping out the new contributors to be able to contribute to it. In some cases that is CONTRIBUTING.md document in the root of a git repo, in others it's a wiki page like How to contribute to Factory, which is likely pretty well known to anyone that has ever pushed anything to Factory. This kind of documentation is something which we would like to help you develop for your branch of contributions, so that other people can help out in a more meaningful way.
There are plenty of helpful resources for writing good contributing guides on the internet[1], though a lot of them apply to code and not necessarily to other forms of contributions. Remember that any contributor can be a newcomer, and may not necessarily understand things that may be obvious to you, and may want to use your repository as their learning experience. Explaining how things come together is one of the primary things that have to be written down. Ruby on Rails application repository doesn't look like a Ruby on Rails application repository to somebody who has never seen one, and even when using Weblate, it's easy to get lost when you first get started.
For software development, we don't want to link people directly to git repos, because even if they are more familiar with concepts like git, programming languages and have coded before, contribution guides explain how the repo in particular is developed, how to test and run software, and what to consider before creating a pull request.
For other forms of contributions, just linking to a homepage is not exactly helpful, we still want to explain how and why to contribute.
It's really important to include some form of contact (mailing list, matrix, irc) to the maintainers and developers of the project.
Projects not directly under openSUSE, but related to it in significant way (like KDE or GNOME upstreams for example) also count as something we would like to have included.
# I have the guide now, how do I include it?
If you don't want to mess around with editing yaml files, feel free to create an issue on asknot-ng GitHub page[2] or get in contact with us with methods listed below.
If you do want to contribute more directly, there are example yaml files from Fedora side of things already[3], while the openSUSE ones[2] are a little bit empty. The existing content in the openSUSE yaml files is not final, I just wanted to get the website working, so feel free to either add your contribution based on the existing branches, or create a new one. The fact that your project is currently listed doesn't mean it will stay that way then, it may just be a placeholder. If you would like to know our opinion on this before you PR, we have the contact info listed below.
Do not worry too much about images, I will likely be going over them later anyway, and will create whatever ends up being required.
# Where will this be hosted?
Currently the plan is contribute.opensuse.org, I have already submitted an MR to host it on our pinot machine, and it's being reviewed. It will likely come up online in the next couple of days for preview purposes, while we work on adding content.
# How do I get in contact with you?
There are a few ways: * GitHub issues on asknot-ng repo[2] * #web:opensuse.org on matrix * #web on discord.gg/opensuse * web@lists.opensuse.org mailing list * #opensuse-web on libera.chat
[1] https://mozillascience.github.io/working-open-workshop/contributing/ also includes follow up resources
[2] https://github.com/openSUSE/asknot-ng
[3] https://github.com/fedora-infra/asknot-ng/blob/develop/questions/fedora.yml https://github.com/fedora-infra/asknot-ng/tree/develop/questions/includes/fe... LCP [Jake] https://lcp.world/
Regards, Florian "sp1rit" -- $\int_\text{now}^{+\infty}\text{Keep trying}$ Matrix: @sp1rit:tchncs.de <sp1rit@disroot.org> D248BF2F4C6A82A1E0569D897D8C1CD573166D09 <sp1rit@national.shitposting.agency> BBDE032EAAFBFC627FB7E635B1F4055D8460CE34
On Di, Aug 16 2022 at 22:22:07 +0200, sp1rit <sp1rit@national.shitposting.agency> wrote:
Just took a look at whatcanidoforfedora.org and I really dislike the way options are presented. The problem is, that you could likely help with more than just one thing the project needs, but the UI/UX makes the guides impossible to properly see and navigate.
Have you thought about providing a separate page that just displays all avilable guides in some kind of tree-view (for example a staggered table)?
The script itself supports outputting the tree like that, so it's possible, though it's mostly for debugging purposes. It shouldn't be much of an issue to accommodate this though. LCP [Jake] https://lcp.world/
On Tue, Aug 16, 2022 at 8:54 PM Jacob Michalskie <hellcp@opensuse.org> wrote:
On Di, Aug 16 2022 at 22:22:07 +0200, sp1rit <sp1rit@national.shitposting.agency> wrote:
Just took a look at whatcanidoforfedora.org and I really dislike the way options are presented. The problem is, that you could likely help with more than just one thing the project needs, but the UI/UX makes the guides impossible to properly see and navigate.
Have you thought about providing a separate page that just displays all avilable guides in some kind of tree-view (for example a staggered table)?
The script itself supports outputting the tree like that, so it's possible, though it's mostly for debugging purposes. It shouldn't be much of an issue to accommodate this though.
That generally tends to overwhelm new people trying to find *something* to do, which is why the site doesn't do that by default. -- 真実はいつも一つ！/ Always, there's only one truth!
On Tue, 2022-08-16 at 21:19 -0400, Neal Gompa wrote:
On Tue, Aug 16, 2022 at 8:54 PM Jacob Michalskie <hellcp@opensuse.org> wrote:
On Di, Aug 16 2022 at 22:22:07 +0200, sp1rit <sp1rit@national.shitposting.agency> wrote:
Just took a look at whatcanidoforfedora.org and I really dislike the way options are presented. The problem is, that you could likely help with more than just one thing the project needs, but the UI/UX makes the guides impossible to properly see and navigate.
Have you thought about providing a separate page that just displays all avilable guides in some kind of tree-view (for example a staggered table)?
The script itself supports outputting the tree like that, so it's possible, though it's mostly for debugging purposes. It shouldn't be much of an issue to accommodate this though.
That generally tends to overwhelm new people trying to find *something* to do, which is why the site doesn't do that by default.
I think that depends on the type of people looking at it. I'd assume a lot people wanting/looking into contributing to the project are already technically versed. And I don't think it should be too overwhelming (esp. for theese kind of people) if the leafs are collapsed by default. -- $\int_\text{now}^{+\infty}\text{Keep trying}$ Matrix: @sp1rit:tchncs.de <sp1rit@disroot.org> D248BF2F4C6A82A1E0569D897D8C1CD573166D09 <sp1rit@national.shitposting.agency> BBDE032EAAFBFC627FB7E635B1F4055D8460CE34
On 2022-08-17 02:48, Jacob Michalskie wrote:
On Di, Aug 16 2022 at 22:22:07 +0200, sp1rit <sp1rit@national.shitposting.agency> wrote:
Just took a look at whatcanidoforfedora.org and I really dislike the way options are presented. The problem is, that you could likely help with more than just one thing the project needs, but the UI/UX makes the guides impossible to properly see and navigate.
Have you thought about providing a separate page that just displays all avilable guides in some kind of tree-view (for example a staggered table)?
The script itself supports outputting the tree like that, so it's possible, though it's mostly for debugging purposes. It shouldn't be much of an issue to accommodate this though.
LCP [Jake] https://lcp.world/
We took a look at this in last night's meeting and added a marketing.yml with pull request - https://github.com/openSUSE/asknot-ng/pull/1 We also made a list of topics for the coding.yml to add 10 coding topics. You can view those at https://etherpad.opensuse.org/p/weeklymeeting20220818 We plan to work on these in the next Thursday meeting. v/r Doug
participants (4)
-
ddemaio -
Jacob Michalskie -
Neal Gompa -
sp1rit