How to Contribute?

We want Nexus to serve also as a place where members of the community can share their knowledge. This guide answers the question, how to contribute to Nexus?

What kinds of resources are hosted on Nexus?

Any content (original or external) that can help make the practice of ML more connected, accessible, efficient, and reproducible is welcome on the Nexus platform! This includes, but is not limited to:

• 🧠 Educational materials: Explore a library of educational materials (workshops, guides, books, videos, etc.) covering a wide range of ML-related topics, tools, and workflows, from foundational concepts to advanced techniques. These materials offer clear explanations, practical examples, and actionable insights to help you navigate the complexities of ML with confidence.

• 🧬 Applications & stories: Discover a curated collection of blogs, papers, and talks which dive into real-world ML applications and lessons learned by practitioners. This section also includes exploratory data analysis (EDA) case studies, which demonstrate the technical and domain knowledge needed to explore data from various fields.

• 🛠 Models, code, and more: Learn about popular pretrained & foundation models, useful scripts, and datasets that you can leverage for your next ML project. Learn about their features, how to use them effectively, and see examples of them in action.

Need inspiration for a good topic to post about?

An ever-expanding list of requested resources can be found on the Issues page (on GitHub). Search for open issues that have the “Resource” label to check out some of our top priorities. If you’d like to tackle a given issue, please comment on the issue to let others know.

What makes a good post?

Creating a useful and engaging post for the ML+X Nexus involves a few key elements to ensure it is beneficial for the community. Here are some general guidelines to follow:

Clear and concise title

The title should accurately reflect the content and main focus of the post. It should be engaging and specific, allowing readers to quickly understand what they can expect.

Detailed description

Provide a comprehensive overview of the resource or topic. This should include:

• Purpose and scope: Clearly state what the resource covers and its main objectives. Explain why the content is valuable and how it can help practitioners.

• Key features: Highlight the unique aspects or strengths of the resource. This could include practical examples, interactive elements, or real-world applications.

• Strengths and weaknesses: Provide a balanced view by discussing both the strengths and any potential limitations of the resource. This helps users make informed decisions about whether the resource is right for them.

Prerequisites

List any necessary background knowledge or skills required to fully benefit from the resource. This helps set expectations and ensures that users are adequately prepared. Include links to additional resources or tutorials that can help users gain the required knowledge.

Estimated time to complete

Offer an estimate of the time commitment needed to complete the resource. This helps users plan their learning activities and manage their time effectively.

Accessibility and usability

Ensure the resource is easy to access and use. We want the majority of resources on Nexus to be free and open source (with possibly a few rare exceptions for tools/resources in high-demand). Provide clear instructions on how to navigate and utilize the content. If the resource is hosted externally, include a direct link and any necessary login or access information.

Additional related resources

Include links to related materials or further readings that can enhance the user’s understanding and provide more in-depth knowledge on the topic. This can include books, articles, other workshops, or case studies. When possible, link to any relevant materials which are already hosted on the Nexus platform.

Examples of good posts

Please see below for a list of resources that meet our platform’s standards. You can use these examples in conjunction with the template files provided in the next section to create your post.

Recommended “Learn” resources

• Workshop
• Book
• Video

Original “Learn” resources

• Guide

Recommended “Application” resources

• Playlist
• “Highlight” (single talk)

How to make a new post with GitHub?

GitHub collaboration model

We follow GitHub’s collaboration model, so the general idea to make a post or edit a document is the same. The high-level steps include:

1. Create an issue announcing your plan to add a resource — see ML+X Nexus Issues
2. Fork the ML+X-Nexus repository
3. Clone the forked repository onto your local machine
4. Create a new branch
5. Write the post, commit and push the changes
6. Make a pull request

If you don’t know how to use Git / GitHub already, it can be a little intimidating at first. A friendlier alternative could be to download GitHub desktop and add your post using the instructions provided below. If you’d like to learn more about GitHub Desktop, check out the Version Control with GitHub Desktop guide on Nexus. If you need additional help (and work in a research lab at UW-Madison), you may also seek help at the Data Science Hub’s office hours (“Coding Meetup”).

1. Get Started with GitHub Desktop

1. Go to the GitHub Desktop website and download the application for your operating system. Install GitHub Desktop by following the on-screen instructions.
2. Open GitHub Desktop and sign in with your GitHub account. If you don’t have one, you will need to create your GitHub account first.

2. Create an Issue on Nexus GitHub

Before you start writing your content, create an issue on the Nexus GitHub to announce your intended addition. This helps the Nexus development team keep track of new contributions and provides an opportunity for feedback.

1. Go to the Nexus GitHub Issues page
2. Click on the New Issue button.
3. Title the issue with the name of your resource, and add a “Resource” label/tag (found on right side panel of issue post).
4. Describe why you think this resource should be included on the Nexus platform.
5. Wait for feedback: Wait for one of the Nexus developers to provide feedback or comments on your issue before proceeding.

3. Fork the Repository

1. Go to the ML+X-Nexus repository on GitHub.
2. Click the Fork button at the top-right corner of the page. This will create a copy of the repository under your GitHub account.

4. Clone the Repository to Your System to Your Local System

1. From your new forked version of the repo on GitHub, click the green Code button to copy the HTTPS URL of the fork
2. In GitHub Desktop, click on File > Clone Repository.
3. Paste the URL and click Clone

5. Create a New Branch

1. In GitHub Desktop, click on Branch > New Branch.
2. Name your new branch descriptively based on the resource type and name (e.g., workshop-introDL, video-NeurIPS2024, etc.).

6. Write Your Post

1. Open your favorite text editor or IDE (e.g., Visual Studio Code, Sublime Text).
2. Write your post in the appropriate format. Follow the guidelines in the next section for writing a good post, making use the template file provided.

7. Commit and Push Changes

1. In GitHub Desktop, you should see your changes listed under Changes.
2. Write a descriptive commit message (e.g., Add new resource: workshop-introDL).
3. Click Commit to your-branch-name.
4. Click on Repository > Push to push your changes to GitHub.

8. Make a Pull Request

1. Go to your forked repository on GitHub.
2. Click on the Compare & pull request button.
3. Ensure you are merging into the “main” branch of the ML+X-Nexus repository.
4. Write a descriptive title and comment for your pull request.
5. Click Create pull request.

9. Wait for Review

1. One of the Nexus developers will review your pull request. They may provide feedback or request changes.
2. Address any feedback and push additional commits as needed.

How to write the post? Start with a template!

External resources

If you are adding an external resource, please start with one of the relevant template files linked below. There are comments in each template that will help you make the appropriate edits for your resource. You can also check out how other posts have been formatted by clicking “Improve this page” from a given post’s webpage. This will bring you directly to the qmd file for that post.

• “Learn” resource: workshop, book, guide, video lecture, etc.
• Application - talk/video
• Application - blog

Orginal content

To write a post, there are many options: Write it using quarto, rmarkdown, or jupyter. The post could be a new file in the appropriate folder (Resources, ML-stories, or EDA), or a named folder with an index.[ipynb|qmd|rmd|md] extension. In any case, the header of the post needs to be a yaml section with the fields:

---
title: An Example
description: |
  An exploratory data analysis example
author: ML+X
date-modified: "last-modified"
date-format: long
categories:
  - EDA
  - PCA
---

The only fields that need to be changed are title, description, author and the categories. Ideally the categories should match the tags that are already in use in the site, e.g. if tag that we are using for support vector machines is SVM then use that one instead of writing another one like support-vector-machines. You can also check out how other posts have been formatted by clicking “Improve this page” from a given post’s webpage. This will bring you directly to the qmd file for that post.

Where to locate your post?

We want the site to be constantly evolving with the community, and our intention is to keep the contributions to the site as free as possible. However, we added some sections to structure the site a little bit:

├── Applications
│   ├── Blogs
│   ├── EDA-examples
│   ├── Highlights # Videos
│   ├── Papers
│   ├── Playlists
├── Learn
│   ├── Books
│   ├── Guides
│   ├── Videos
│   ├── Workshops
├── Toolbox
│   ├── Code
│   ├── Compute
│   ├── Data 
│   ├── Models 

Note: Some subfolders may not exist yet (e.g., Code, Data) since no one has contributed a resource from one of those categories yet, and git doesn’t allow empty folders. Feel free to start one of the missing folders, if applicable. If your resource doesn’t belong to one of the categories listed above, you may add a new one. We’ll discuss this new category when we review your initial “Issue” announcing the resource addition.

How to improve an existing post?

Want to add a code-long exercise to an existing post, add your perspective, or correct a typo? Anyone is welcome and encouraged to suggest improvements to existing materials hosted on Nexus! The most straightforward way to do this is to click “Improve this page” from the post’s webpage on Nexus to suggest your edits. The below steps will walk you through this process.

Steps to improve a post on Nexus via GitHub (no software installation needed):

1. Click “Improve this page”: This will redirect you to the GitHub repository where the content of the post is stored.

2. Edit the file directly on GitHub:

   • On the GitHub page, click the pencil icon (✏️) at the top right of the file to edit the content directly in your browser. No need to install any git software!
   • Make your changes in the text editor. You can add a code-long exercise, share your perspective, or correct any typos.

3. Commit your changes:

   • After you have made your edits, scroll down to the “Commit changes” section.
   • Write a brief description of what you changed.
   • Choose the option to “Create a new branch for this commit and start a pull request.”

4. Create a pull request:

   • Click the “Propose changes” button.
   • You will be taken to a new page where you can review your changes.
   • Click “Create pull request” to submit your changes for review.

Congratulations! You have suggested an improvement to a Nexus post. The repository maintainers will review your pull request, and if everything looks good, your changes will be merged into the post.

Note: While you can make these edits directly on GitHub without any software installation, we recommend all ML practitioners learn git! Check out our git category search resources.

Questions?

If you any lingering questions on how to contribute, please feel free to post to the Nexus Q&A on GitHub. We will improve this guide based on additional questions/comments we receive.