Skip to content

Latest commit

 

History

History
144 lines (107 loc) · 4.49 KB

Contribution Guide.md

File metadata and controls

144 lines (107 loc) · 4.49 KB

Contribution Guide for MLA2Z Jupyter/Colab Notebooks

Welcome to the MLA2Z open-source project! We aim to create engaging, interactive, and conversational learning experiences in the field of machine learning. This guide provides a structure and best practices for contributing to our course modules using Jupyter or Colab notebooks.

How to Structure Your Notebook Content

  1. Conversational Style:

    • The content should feel like a dialogue between a teacher ("You") and a student ("Me").
    • Example: 
      You: What is the purpose of a DataFrame in pandas?

Me: A DataFrame is a two-dimensional labeled data structure, similar to a table in a database.

You: Can you show me how to create one?

Me: Sure! Here's an example:
      import pandas as pd

data = {'Name': ['Alice', 'Bob'], 'Age': [25, 30]}
df = pd.DataFrame(data)
print(df)

  2. Course Modules and Stages:

    • Each module is divided into topics, and each topic is divided into five stages.

      Example:

      • Module 3: pandas
        • Topic 1: Introduction to pandas
          • Stage 0: Basics of pandas and its use in data manipulation
          • Stage 1: DataFrames and Series
          • Stage 2: Data cleaning and preprocessing with pandas
          • Stage 3: Advanced data operations
          • Stage 4: Interview Questions

  3. Interactive and Practical Approach:

    • Start each stage with simple explanations and examples.
    • Gradually move towards more complex scenarios.
    • Encourage learners to try coding along with the explanations.

  4. Code Examples:

    • Include code snippets wherever necessary.
    • Annotate the code with inline comments to explain each step.

  5. Questions for Engagement:

    • Ask questions to guide the learner through the thought process.
    • Provide hints or solutions where appropriate.

Writing Best Practices

  1. Keep It Simple:

    • Use plain language and avoid unnecessary jargon.
    • Assume the learner is encountering the concept for the first time.

  2. Visual Aids:

    • Use tables, charts, or diagrams where helpful.
    • Use Markdown for text formatting to improve readability.

  3. Notebook Structure:

    • Start with an introduction explaining the objective of the notebook.
    • Divide the notebook into clear sections:
      • Introduction: High-level overview of the topic.
      • Concepts: Detailed explanation of key ideas.
      • Examples: Practical coding examples.
      • Exercises: Hands-on tasks for learners.
      • Summary: Key takeaways.

  4. Stage-Specific Tips:

    • Stage 0: Lay the groundwork for the topic with simple examples.
    • Stage 1: Introduce foundational elements like DataFrames or Series.
    • Stage 2: Cover practical applications like data cleaning.
    • Stage 3: Dive into advanced concepts.
    • Stage 4: Provide interview-style questions to reinforce learning.

Guidelines for Contributors

  1. Consistency:

    • Follow the conversational style and modular structure.
    • Use consistent formatting for headers, code, and text.

  2. Collaboration:

    • Review existing notebooks on MLA2Z Course Modules.
    • Ensure your contribution aligns with the overall tone and objectives.

  3. Testing:

    • Test all code snippets to ensure they run without errors.
    • Include example outputs where applicable.

  4. Version Control:

    • Commit your work regularly with clear, descriptive commit messages.
    • Submit pull requests with a detailed explanation of the changes.

  5. License Compliance:

    • Ensure all contributions adhere to the project’s open-source license.

Example Notebook Snippet

### Stage 1: DataFrames and Series

You: How do we create a pandas DataFrame?

Me: Let’s start with a dictionary of data and convert it into a DataFrame:
import pandas as pd

data = {
    'Name': ['Alice', 'Bob', 'Charlie'],
    'Age': [25, 30, 35],
    'City': ['New York', 'Los Angeles', 'Chicago']
}

df = pd.DataFrame(data)
print(df)
You: What if I only want the names and ages?

Me: You can use the following code:
print(df[['Name', 'Age']])
### Exercise:
Try creating a DataFrame with your own data and print specific columns.

By following these guidelines, we can create high-quality, engaging content for learners. Thank you for contributing!