[📑 Docs]: create "Contributors Needed" cards to encourage contributions

[quetzalliwrites]

What Dev Docs changes are you proposing?

Proposed Improvement

As part of the new Information Architecture (IA) changes proposed via https://github.com/asyncapi/website/issues/350 and https://github.com/asyncapi/website/issues/503, this issue proposes addressing a ✨new contribution idea✨ that was born from a comment within issue #350.

As documented in this comment, it was proposed that we create Contributors Needed cards to encourage contributions.

Each content bucket landing page could include cards featuring content the community has already requested but that we still need contributions for. Instead of having a card that merely says "coming soon," we could have the cards read, "Contributors Needed - Kafka Tutorial."

Teaming w/ Design and Development

I would love to hear from @mcturco and/or from our other Design contributors how we propose it should look like.

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[quetzalliwrites]

@derberg, your idea finally has it's own issue 😄🎉🎉

[derberg]

love it! would it be a "clickable" banner linking to some instructions? video?

[quetzalliwrites]

love it! would it be a "clickable" banner linking to some instructions? video?

good idea/question! hmm.. I think the card should be a component that can link to individual instruction pages for each contribution idea card displayed. @derberg

[derberg]

sure, might be some work, but this would be ultimate great goal, and fallback could be a link to some generic video about how to contribute to AsyncAPI docs, some tutorial or something. Something similar we have about contributing to spec

[quetzalliwrites]

sure, might be some work, but this would be ultimate great goal...

@derberg Yeah, true... this will def be more work cause it means new page for each contribution card 🤔 💭

and fallback could be a link to some generic video about how to contribute to AsyncAPI docs, some tutorial or something. Something similar we have about contributing to spec

I think a fallback can be to have ONE generic docs page that lists the steps to contribute to the Docs. Something similar to this...

---

How do I get started contributing to this ticket for AsyncAPI Docs?

Don't forget that code isn't the only way to contribute to OSS; Dev Docs are a huge help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️

To get started as a Docs contributor:

1. Familiarize yourself with our project's Contribution Guide and our Code of Conduct.
2. Head over to our Docs GH Board here and bookmark it.
3. Lleave a comment in the issue you're pickin up and introduce yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. Open a PR and get started!

🏷 Tag Alejandra Quetzalli in your AsyncAPI Doc PRs

Do you have a documentation contributor question and you're wondering how to tag Alejandra into your GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or GitHub Discussions via my GitHub handle, alequetzalli 🐙.

[derberg]

sounds good

[mharshita]

@alequetzalli I want to work on this issue.

[quetzalliwrites]

@mharshita awesome, go for it! ❤️

[mharshita]

hey @alequetzalli! I am attaching a screenshot of a general idea of the Contributors Needed card (just an idea of what I understood till now). Please suggest improvements for this.

[quetzalliwrites]

Let's get @mcturco to give you feedback on design contributions @mharshita ⭐

[mcturco]

Hi! Nice, @mharshita thank you for submitting this idea!

After reading the previous comments in the issue, I want to confirm with @alequetzalli and @derberg that the idea for these "Contributors Needed" cards is to have a CTA banner with a button that links to a docs page with the information listed in the above comment by @alequetzalli

If that is correct, I am wondering if the "Contributors Needed" cards as mocked up by @mharshita need to contain specifics on the contributions needed or should it just link out to the issue where the user would go to make the contribution? Just want to make sure I am clear on the goal of this issue before I offer my suggestions 😄

[derberg]

I would say there definitely is a need for How to contribute link to link to generic instructions. As for the Create Issue on GitHub 🤔 @alequetzalli what do you think, I think just as proposed by @mharshita, we should have a call to action to create issue instead of having multiple issues created upfront.

[quetzalliwrites]

@mcturco @derberg (cc @mharshita) Ah, good questions all around! 😺

Here's my take on what Contributor Needed cards should include/do:

• personalized title of needed contribution (i.e., "Contributors needed for Kafka tutorial")
• CTA button that links to creating a new Docs issue.

🚨 Edge cases: How do you folks want to handle the edge case of contributions needed that already have a GH docs issue created in our board? We cannot assume that new contributions will always need a new GH issue created.

⚠️ NOTE: I do not think we need to duplicate content and have the cards link to another explanation of how to contribute. PR 601 includes the new /Overview landing pages already including that info. Contributor Needed cards will be placed only on /Overview pages, which, as we just stated, already include info on how to contribute to that area.

[derberg]

🚨 Edge cases: How do you folks want to handle the edge case of contributions needed that already have a GH docs issue created in our board? We cannot assume that new contributions will always need a new GH issue created.

it might happen but the complexity to solve is not worth the effort IMHO, especially compared to effort of just closing a few duplicated issues

[mharshita]

I agree with @derberg. What are your views @alequetzalli @mcturco ?

[quetzalliwrites]

@derberg @mcturco @mharshita

Totally agree on the solving equation. But here's what I'm curious about...

What if the contributor needed cards could either link directly to an open issue or include a cta to create issue?

If we could remove in our markup the cta or add the link, we can manually add each contribution card and determine if it can link directly or if it needs a new issue.

Shouldn't it be easy to have that flexibility? 🤔

[mcturco]

@derberg @alequetzalli @mharshita

Hmmmm 🤔

IMO, It seems kind of weird that we would include a "Contributors Needed" card on a docs page without ALREADY having an issue open for the contribution that we are asking for. Wouldn't you already have some details on the contribution needed? I feel like before we add a "Contributors Needed" card to a docs page, we should remember to open an issue first, and then link it right within the cards when adding it in a PR. To me, if we do it this way, it can get the potential contributor the information they need to start contributing right away other that creating confusion on whether an issue has been opened on that specific topic yet.

What does everyone else think about that?

[derberg]

hmmm, I'm not sure I recall correctly, but I guess idea was that this card is visible only there where contribution is needed 🤔

my only concern with opening an issue upfront, is that it can bother us later through stale issue notification + there is a high probability that after contribution we forget to remove reference to already closed issue

[mcturco]

Yeah, but I think it is a bigger concern for the action in the cards to be "Create an issue" because what if someone already created an issue? Then you would need to update the website again to keep others from creating duplicate issues. It's going to be a matter of weighing out what problem is the least annoying haha 😄

[derberg]

annoying vs expensive 🤣

[quetzalliwrites]

I agree with @mcturco, let's make it our workflow to create an issue FIRST and then add a contributor needed card linking to it.

I agree/understand that getting stale notifications on those tickets could suck, but I think we need to select clarity over simplicity.

If we follow Missy's approach, then it will be extremely clear and simple for each contributor to click thro the card and find the info needed to start a PR right away. I want us to take this approach.

[mharshita]

Sorry, my exams are going on, so that's why late reply. I will go ahead with Missy's approach.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: