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:

Core Topics (/core)
Theoretical concepts
Programming examples
Best practices
Implementation guides
Industry Applications (/industry)
Case studies
Real-world implementations
Industry-specific guides
Project examples
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¶

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

Fork & Setup

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

Create Content
Use appropriate template based on contribution type
Follow folder structure conventions
Include necessary cross-references
Quality Guidelines
Write clear, concise content
Include practical examples
Link to related topics
Add references and citations
Follow markdown best practices

Submit Changes

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

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

Content Generation Tools¶

✍️ For an end-to-end workflow using Obsidian + Claude (and how to keep notes MkDocs-compatible), see the Authoring Guide.

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¶

Writing Style
Use clear, professional language
Avoid jargon without explanation
Include practical examples
Cross-reference related topics
Code Style
Follow language-specific conventions
Include comments and documentation
Provide working examples
Test before submission
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!