PROCESS CHANGE: Enhancing Onboarding

[prajjwalyd]

One of the recommendations for enhancing the contributor experience in Knative, as outlined in the Contributor Experience Research 2024, is to enhance the current onboarding process for new contributors and establish a 'structured onboarding plan'.

Here's a breakdown of the proposal:

Improving the Onboarding Process

• Establishing a Structured Onboarding Plan

  • This plan should include comprehensive introductory documentation, guides, tutorials, and links to all other necessary resources. This approach allows new contributors to seamlessly integrate themselves into the project with minimal friction.
  • Consolidating this plan into a centralized hub, such as a digital book or repository, would provide immense value for new contributors. Perhaps we can include this 'centralized resource' in the issue templates to make it easier to find, especially for newcomers.

• Video tutorials & Visual Guides

  • Creating detailed video tutorials for setting up Knative projects on popular operating systems like Linux/WSL and macOS is essential for new contributors.
  • These tutorials would provide step-by-step instructions for installation and configuration, along with an overview of different components and directories.
  • Visual guides (diagrams, flowcharts, etc.) to simplify understanding and empower contributors to overcome initial hurdles more effectively.

• Clear Communication of Expectations

  • PR Guidelines: Clearly communicate expectations for pull requests (PRs). This includes providing a detailed guide on the PR process, common review criteria, and typical feedback cycles.
  • By setting clear expectations upfront, new contributors will be better prepared for the collaborative nature of open-source contributions, reducing the likelihood of feeling overwhelmed by feedback on their initial submissions.

Why is it needed?

• Reducing Initial Setup Frustration: Many new contributors face significant challenges during the initial setup phase, which can lead to frustration and potentially abandoning the project. Comprehensive onboarding resources, including video tutorials and visual guides, provide a guided approach to help them navigate this phase confidently.

• Empowering New Contributors: Beginner-friendly resources and documentation are particularly crucial for those new to Knative and cloud-native technologies like Docker and Kubernetes. Structured and accessible onboarding materials help these individuals to understand the project and make meaningful contributions without facing significant challenges.

• Sustaining Engagement: Clear communication of PR expectations helps maintain contributor engagement by preparing them for the iterative feedback process, reducing frustration and encouraging continuous involvement.

Implementation:

1. Establishing a Structured Onboarding Plan:
   • Content Creation: Create comprehensive documentation, guides, and tutorials covering all important aspects of the project. Review and update the existing material for each Knative component.
   • Centralized Hub: Develop a centralized accessible resource or digital book (something similar to the Layer5 Community Handbook) to consolidate all important community and onboarding materials.
   • Integration: Include links to the centralized resource in issue templates for easy access. Also, showcase this on knative.dev to increase visibility.
   • Quality Testing and Improvements: Regularly evaluate the onboarding plan with experienced community members and gather feedback from new contributors, using their insights and suggestions to enhance the process.
2. Comprehensive Video Tutorials:
   • Video Production: Produce detailed video tutorials for setting up Knative projects on popular operating systems.
   • Content Coverage: Ensure the tutorials cover installation, configuration, and an overview of project directories and components.
   • Distribution: Upload the videos to YouTube and embed them in relevant documentation.
3. Clear Communication of Expectations:
   • Guideline Creation: Develop clear guidelines for pull requests (PRs), including expectations, timeline, and iterative review processes.
   • Documentation: Document the PR process and expectations in the contributing guidelines.

[Cali0707]

/cc @knative/steering-committee @knative/technical-oversight-committee

[dprotaso]

I like the overall idea

Video Production: Produce detailed video tutorials for setting up Knative projects on popular operating systems.

This is a lot of work - I would probably not do this for dev setup because that changes pretty frequently. Ideally we do this for topics that are relatively stable

[aliok]

How about we post some social media posts, asking for people with video skills to go through the development environment setup and record a video? It doesn't have to be professional quality.

[aliok]

Centralized Hub: Develop a centralized accessible resource or digital book (something similar to the Layer5 Community Handbook) to consolidate all important community and onboarding materials.

We already have lots of resources (https://knative.dev/docs/community/), but they're not as good looking as Layer5. This might be something we can actually do. We have the material available, but they're spread over.

[aliok]

I just created a task to recruit contributors who can evaluate the Knative Eventing onboarding. If this works out, we can do the same with other Knative modules.

knative/eventing#8111