Skip to content

Latest commit

 

History

History
403 lines (317 loc) · 8.97 KB

CONTRIBUTING.md

File metadata and controls

403 lines (317 loc) · 8.97 KB

Contributing Guidelines

Welcome to the Computer Science Notebook! We're excited to have you contribute to this knowledge base that bridges theoretical computer science with real-world applications.

Project Structure

computer-science-notebook/
├── core/                     # Core CS concepts
├── industry/                # Industry applications
└── meta/                    # Resources & docs

How to Contribute

You can contribute to any of these main areas:

  1. Core Topics (/core)

    • Theoretical concepts
    • Programming examples
    • Best practices
    • Implementation guides

  2. Industry Applications (/industry)

    • Case studies
    • Real-world implementations
    • Industry-specific guides
    • Project examples

  3. Meta Resources (/meta)

    • Documentation
    • Learning resources
    • Career guides
    • Project tools

Document Templates

Core Topic Template

core/<topic-area>/<specific-topic>/
│   README.md
│   topic-guide.md
├── concepts/
│   └── core-concepts.md
├── examples/
│   └── implementation.md
├── resources/
│   └── additional-materials.md
└── industry-applications/
    └── industry-links.md

Industry Application Template

industry/<sector>/<application>/
│   README.md
│   overview.md
├── case-studies/
│   └── example-implementation.md
├── technical-guide/
│   └── implementation-details.md
└── core-topics/
    └── related-concepts.md

Content Guidelines

README.md Format

# Topic Title

![Optional Topic Image]()

## Overview
Brief description of the topic/application

## Key Concepts
- Core concept 1
- Core concept 2
- Core concept 3

## Quick Start
Basic getting started guide

## Related Topics
Links to related content

## Contributing
How to contribute to this section

Technical Content Format

# {Topic} Technical Notes
[image with prompt description]

## Quick Reference
- One-sentence definition
- Key use cases
- Prerequisites [scales with audience level]

## Content Overview
[Auto-generated sections based on audience level and focus area]

## Introduction
- What: Core definition and purpose
- Why: Problem it solves/value proposition
- Where: Application domains
[Depth scales with audience level]

## Core Concepts
### Fundamental Understanding
- Basic principles [scales with audience level]
- Key components
- Common misconceptions [audience-specific]

### Visual Architecture
[Mermaid diagrams - complexity scales with level]
- System overview
- Component relationships
[Technical depth based on focus area]

## Implementation Details
[Scales significantly based on audience level]

### Basic Implementation [Beginner]
```[language]
// Basic working example with detailed comments
``
- Step-by-step setup
- Code walkthrough
- Common pitfalls

### Intermediate Patterns [Intermediate]
```[language]
// Basic working example with detailed comments
``
- Design patterns
- Best practices
- Performance considerations

### Advanced Topics [Advanced]
```[language]
// Basic working example with detailed comments
``
- System design
- Optimization techniques
- Production considerations

## Real-World Applications
[Focus area specific]
### Industry Examples
- Use cases [complexity scales with level]
- Implementation patterns
- Success metrics

### Hands-On Project
[One focused project matching audience level]
- Project goals
- Implementation steps
- Validation methods

## Tools & Resources
[Curated based on audience level]
### Essential Tools
- Development environment
- Key frameworks
- Testing tools

### Learning Resources
- Documentation
- Tutorials
- Community resources

## References
- Official documentation
- Technical papers
- Industry standards
[Depth varies by focus area]

## Appendix
[Optional sections based on focus area]
- Glossary
- Setup guides
- Code templates

Contribution Process

  1. Select Your Focus

    • Choose between core topics, industry applications, or meta resources
    • Check existing content to avoid duplication
    • Identify gaps in current documentation

  2. Fork & Setup

    git clone https://github.com/your-username/computer-science-notebook
cd computer-science-notebook
git checkout -b feature/your-contribution

  3. Create Content

    • Use appropriate template based on contribution type
    • Follow folder structure conventions
    • Include necessary cross-references

  4. Quality Guidelines

    • Write clear, concise content
    • Include practical examples
    • Link to related topics
    • Add references and citations
    • Follow markdown best practices

  5. Submit Changes

    git add .
git commit -m 'Add: brief description of changes'
git push origin feature/your-contribution

  6. Create Pull Request

    • Use the PR template
    • Link related issues
    • Provide clear description
    • Request review from maintainers

Content Generation Tools

Using the Note Generator

python tools/generate.py --type <core|industry|meta> --path <path> --name <topic-name>

AI-Assisted Content Generation

You can use the following prompt template with AI tools:

Your task will be to generate a technical guide for [TOPIC] following this structure:

```markdown
# {Topic} Technical Notes
[Long and descriptive Prompt description of image in rectangular format]

## Quick Reference
- One-sentence definition
- Key use cases
- Prerequisites [scales with audience level]

## Table of Contents
[Auto-generated sections based on audience level and focus area]

## Introduction
- What: Core definition and purpose
- Why: Problem it solves/value proposition
- Where: Application domains
[Depth scales with audience level]

## Core Concepts
### Fundamental Understanding
- Basic principles [scales with audience level]
- Key components
- Common misconceptions [audience-specific]

### Visual Architecture
[Mermaid diagrams - complexity scales with level]
- System overview
- Component relationships
[Technical depth based on focus area]

## Implementation Details
[Scales significantly based on audience level]

### Basic Implementation [Beginner]
```[language]
// Basic working example with detailed comments
``
- Step-by-step setup
- Code walkthrough
- Common pitfalls

### Intermediate Patterns [Intermediate]
```[language]
// Basic working example with detailed comments
``
- Design patterns
- Best practices
- Performance considerations

### Advanced Topics [Advanced]
```[language]
// Basic working example with detailed comments
``
- System design
- Optimization techniques
- Production considerations

## Real-World Applications
[Focus area specific]
### Industry Examples
- Use cases [complexity scales with level]
- Implementation patterns
- Success metrics

### Hands-On Project
[One focused project matching audience level]
- Project goals
- Implementation steps
- Validation methods

## Tools & Resources
[Curated based on audience level]
### Essential Tools
- Development environment
- Key frameworks
- Testing tools

### Learning Resources
- Documentation
- Tutorials
- Community resources

## References
- Official documentation
- Technical papers
- Industry standards
[Depth varies by focus area]

## Appendix
[Optional sections based on focus area]
- Glossary
- Setup guides
- Code templates


Rules:

Target audience: [beginner/intermediate/advanced]

- Beginner: 

[Template would emphasize fundamental understanding, basic implementations, and learning resources while minimizing advanced topics]

- intermediate:

[Template would emphasize design patterns, best practices, and performance considerations while assuming fundamental knowledge and minimizing advanced topics]

- Advanced:

[Template would focus on production implementations, system design, and real-world case studies while assuming fundamental knowledge]

Focus area: [core concept/industry application]

Do you understand?

Usage Example:

- Topic: Machine Learning
- Target audience: Beginner
- Focus area: Core Concepts/industry application

Style Guidelines

  1. Writing Style

    • Use clear, professional language
    • Avoid jargon without explanation
    • Include practical examples
    • Cross-reference related topics

  2. Code Style

    • Follow language-specific conventions
    • Include comments and documentation
    • Provide working examples
    • Test before submission

  3. Documentation

    • Use consistent formatting
    • Include table of contents
    • Add diagrams where helpful
    • Cite sources and references

Getting Help

  • Create an issue for questions
  • Join our community discussions
  • Read our FAQ in the wiki
  • Contact maintainers directly

Recognition

Contributors are recognized through:

  • Contributors list in README
  • Author credits in documents
  • Contribution badges
  • Community highlights

Remember: Quality over quantity. We value well-thought-out contributions that help others learn and understand complex topics.

Thank you for contributing to making computer science education more accessible to everyone!