CONTRIBUTING.md

🚀 Contributing to Agents Towards Production

Thank you for your interest in contributing! This guide covers our standards for creating high-quality tutorials.

📢 IMPORTANT: Signup and Tracking

If your tutorial requires users to sign up for a service:

1. Place signup instructions prominently at the beginning
2. Provide clear, step-by-step signup guidance
3. Always use UTM-tagged links: https://service.com/?utm_source=agents-towards-production&utm_medium=github&utm_campaign=tutorial
4. Include screenshots of the signup process

📂 Tutorial Structure

Required Files

Each tutorial folder must contain:

1. README.md - High-level overview explaining:

   • What the tutorial covers
   • Motivation and benefits
   • Key methods and concepts
   • What you will learn
   • Link to the full tutorial notebook

2. Documentation (choose one):

   • Jupyter notebook (.ipynb) - Interactive guide with code cells (use informative filename)
   • OR tutorial.md - Comprehensive guide with extensive screenshots

3. Working Code: app.py or equivalent main file (well-commented)

4. Dependencies: requirements.txt with specific versions

5. Assets: assets/ folder for images, videos, and media

Example Structure

tutorials/your-tutorial-name/
├── README.md                     # High-level overview and motivation
├── app.py                        # Main application code
├── tutorial.md or .ipynb         # Documentation
├── requirements.txt              # Dependencies
└── assets/                       # Media files
    ├── step1_screenshot.png      # Screenshots for each step
    └── final_result.png          # End result

📝 Tutorial Content Structure

1. README.md - High-level overview with motivation, benefits, key methods, and what you'll learn
2. Title and Overview - Clear motivation, benefits, and key methods
3. Detailed Explanation - Cover key components and method details
4. Visual Representation - Include diagrams (use Mermaid → SVG in assets/)
5. Implementation - Step-by-step with code blocks and screenshots
6. Usage Example - Practical demonstration
7. External Tool Integration - Screenshots for each action
8. Additional Considerations - Limitations and improvements

🎯 Content Quality Standards

Overview and Motivation

• Start with comprehensive overview explaining motivation, benefits, and methods
• Help readers understand they're learning horizontal concepts applicable to their use cases
• Clarify implementations are specific examples of broader ideas
• Make explanations detailed enough to understand without running code

Code Quality

• Break down code into small, clear, well-documented blocks
• Add explanations before every code cell describing what happens and why
• Remove unnecessary outputs (pip logs, debug prints)
• Ensure thorough commenting and readability

Content Structure

• Keep tutorials focused and optimal length
• Remove non-essential sections
• Maintain logical flow from concept to implementation
• Avoid overly verbose descriptions

Links and References

• Minimize promotional linking that may cause user drop-off
• Each link appears only once
• All external links must use UTM tracking parameters
• No external blog references
• Focus on high-value content over promotional linking

Visual Elements

• Only include directly relevant logos
• Maintain clean, professional appearance
• Use consistent formatting throughout

✨ Best Practices

For Notebooks

• Each code cell preceded by explanatory markdown
• Clear unnecessary outputs before committing
• Maintain consistent formatting

For Markdown

• Include screenshots for every significant step
• Ensure visual clarity throughout the process

💻 Code Standards

1. Write clean, readable code following best practices
2. Add clear comments explaining complex logic
3. Use consistent formatting
4. Consider language model review for additional improvements

📚 Contribution Process

1. Fork the repository
2. Create feature branch: git checkout -b feature/AmazingFeature
3. Commit changes: git commit -m 'Add some AmazingFeature'
4. Push to branch: git push origin feature/AmazingFeature
5. Open pull request

✅ Pre-PR Checklist

• Tutorial follows required structure with all required files
• README.md included with high-level overview, motivation, key methods, and what you'll learn
• Code runs without errors and is well-commented
• Dependencies listed with appropriate versions
• No sensitive information (API keys, etc.)
• Content Quality:
  • Clear overview and motivation at beginning
  • Appropriately sized, well-documented code blocks
  • Each code cell has explanatory text
  • Optimal tutorial length
  • All links use UTM tracking
  • No excessive/promotional linking or external blog references
  • Self-contained, educational content
• Visual Elements:
  • Only relevant logos included
  • Clean, professional appearance
  • Consistent formatting throughout

Happy contributing! 🚀