265 lines
7.2 KiB
Markdown
265 lines
7.2 KiB
Markdown
# Learn Folder Template
|
|
|
|
This directory contains templates for creating consistent, high quality educational documentation for each project.
|
|
|
|
## What Goes in a learn/ Folder
|
|
|
|
Every completed project should have a `learn/` directory with these four files:
|
|
|
|
1. **00-OVERVIEW.md** - Project introduction, prerequisites, quick start
|
|
2. **01-CONCEPTS.md** - Security concepts and theory
|
|
3. **02-ARCHITECTURE.md** - System design and technical decisions
|
|
4. **03-IMPLEMENTATION.md** - Code walkthrough and how to build it
|
|
5. **04-CHALLENGES.md** - Extension ideas and next steps
|
|
|
|
## Using These Templates
|
|
|
|
### For New Projects
|
|
|
|
When you start a new project:
|
|
|
|
1. Copy this entire template directory to your project:
|
|
```bash
|
|
cp -r .github/learn-folder-template PROJECTS/[difficulty]/[project-name]/learn
|
|
cd PROJECTS/[difficulty]/[project-name]/learn
|
|
```
|
|
|
|
2. Remove this README (you don't need it in the project):
|
|
```bash
|
|
rm README.md
|
|
```
|
|
|
|
3. Fill in each template:
|
|
- Replace `[placeholders]` with actual content
|
|
- Delete sections that don't apply
|
|
- Add sections specific to your project
|
|
- Keep the overall structure
|
|
|
|
4. Write as you build - don't wait until the end
|
|
|
|
### For Existing Projects
|
|
|
|
Backfilling learn/ folders:
|
|
|
|
1. Start with 00-OVERVIEW.md - this is the easiest
|
|
2. Then do 01-CONCEPTS.md - what security ideas does this teach?
|
|
3. Then 02-ARCHITECTURE.md - how is it designed?
|
|
4. Then 03-IMPLEMENTATION.md - walk through the actual code
|
|
5. Finally 04-CHALLENGES.md - how can others extend it?
|
|
|
|
Don't try to do all files at once. One file per session works fine.
|
|
|
|
## Writing Guidelines
|
|
|
|
### Tone and Style
|
|
|
|
**Do:**
|
|
- Write like you're explaining to a smart friend
|
|
- Use concrete examples and real code
|
|
- Explain WHY, not just WHAT
|
|
- Reference actual vulnerabilities and incidents
|
|
- Show common mistakes and how to avoid them
|
|
- Use diagrams and code snippets liberally
|
|
|
|
**Don't:**
|
|
- Sound like a marketing brochure
|
|
- Use buzzwords without explaining them
|
|
- Assume the reader knows everything (or nothing)
|
|
- Write walls of text - break it up
|
|
- Skip the hard parts
|
|
|
|
### Content Depth
|
|
|
|
**00-OVERVIEW.md** - Surface level, get them excited and oriented
|
|
- 5-10 minute read
|
|
- Focus on what and why
|
|
- Light on technical details
|
|
|
|
**01-CONCEPTS.md** - Medium depth, teach the theory
|
|
- 15-20 minute read
|
|
- Explain security concepts thoroughly
|
|
- Use examples and diagrams
|
|
- Reference standards (OWASP, MITRE, etc)
|
|
|
|
**02-ARCHITECTURE.md** - Deep dive on system design
|
|
- 20-30 minute read
|
|
- Show the big picture
|
|
- Explain design decisions and tradeoffs
|
|
- Include diagrams
|
|
|
|
**03-IMPLEMENTATION.md** - Deepest, actual code walkthrough
|
|
- 30-45 minute read
|
|
- Reference real files and line numbers
|
|
- Show actual code from the project
|
|
- Explain step by step
|
|
|
|
**04-CHALLENGES.md** - Mixed depth based on difficulty
|
|
- 10-15 minute read
|
|
- Range from easy to expert
|
|
- Provide hints, not full solutions
|
|
- Encourage experimentation
|
|
|
|
### Code Examples
|
|
|
|
Always show real code from the actual project, not toy examples:
|
|
|
|
```python
|
|
# Good - actual code from the project
|
|
# src/auth/service.py:42-56
|
|
async def authenticate_user(email: str, password: str) -> User:
|
|
user = await user_repo.find_by_email(email)
|
|
if not user or not verify_password(password, user.password_hash):
|
|
raise InvalidCredentials()
|
|
return user
|
|
```
|
|
|
|
```python
|
|
# Bad - generic example
|
|
def login(username, password):
|
|
# check if valid
|
|
return user
|
|
```
|
|
|
|
### Avoiding AI Voice
|
|
|
|
Watch out for these telltale AI patterns:
|
|
|
|
**Em dashes** - Don't use them. Use periods or commas instead.
|
|
```
|
|
Bad: "It's not just about security — it's about building robust systems"
|
|
Good: "This teaches security and system design"
|
|
```
|
|
|
|
**Contrast flips** - The "it's not X, it's Y" pattern
|
|
```
|
|
Bad: "It's not about memorizing syntax — it's about understanding concepts"
|
|
Good: "Focus on understanding concepts, not memorizing syntax"
|
|
```
|
|
|
|
**Perfect hyphenation** - Don't hyphenate every compound modifier
|
|
```
|
|
Bad: "real-time analysis using state-of-the-art machine-learning algorithms"
|
|
Good: "real-time analysis using state of the art machine learning algorithms"
|
|
```
|
|
|
|
Mix it up. Sometimes hyphenate, sometimes don't. Humans are inconsistent.
|
|
|
|
**Generic enthusiasm**
|
|
```
|
|
Bad: "Embark on an exciting journey into the world of cybersecurity!"
|
|
Good: "Learn how rate limiting works by building one from scratch"
|
|
```
|
|
|
|
### Diagrams
|
|
|
|
ASCII diagrams work great:
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ Client │
|
|
└──────┬──────┘
|
|
│
|
|
▼
|
|
┌─────────────┐
|
|
│ API │
|
|
└──────┬──────┘
|
|
│
|
|
▼
|
|
┌─────────────┐
|
|
│ Database │
|
|
└─────────────┘
|
|
```
|
|
|
|
Use them for:
|
|
- Architecture overviews
|
|
- Data flow
|
|
- State machines
|
|
- Layer diagrams
|
|
|
|
### Real World References
|
|
|
|
Ground concepts in reality:
|
|
|
|
**Good:**
|
|
"In the 2017 Equifax breach, attackers exploited a known Apache Struts vulnerability (CVE-2017-5638). This project teaches you how to scan for such vulnerabilities in your dependencies."
|
|
|
|
**Bad:**
|
|
"In today's evolving threat landscape, vulnerability management is critical."
|
|
|
|
## Quality Checklist
|
|
|
|
Before submitting a learn/ folder, check:
|
|
|
|
### 00-OVERVIEW.md
|
|
- [ ] Explains what the project does in 2-3 sentences
|
|
- [ ] Lists specific prerequisites with examples
|
|
- [ ] Includes quick start instructions that work
|
|
- [ ] Shows expected output
|
|
- [ ] Links to other learn/ files
|
|
|
|
### 01-CONCEPTS.md
|
|
- [ ] Explains each security concept thoroughly
|
|
- [ ] Includes real world examples or breaches
|
|
- [ ] Shows common attacks and defenses
|
|
- [ ] References OWASP/MITRE/CWE where relevant
|
|
- [ ] Includes "testing your understanding" questions
|
|
|
|
### 02-ARCHITECTURE.md
|
|
- [ ] High level architecture diagram
|
|
- [ ] Component breakdown
|
|
- [ ] Design decisions with reasoning
|
|
- [ ] Data flow examples
|
|
- [ ] Performance and security considerations
|
|
|
|
### 03-IMPLEMENTATION.md
|
|
- [ ] References actual files and line numbers
|
|
- [ ] Shows real code from the project
|
|
- [ ] Explains WHY, not just WHAT
|
|
- [ ] Includes common pitfalls
|
|
- [ ] Provides debugging tips
|
|
|
|
### 04-CHALLENGES.md
|
|
- [ ] Mix of difficulty levels
|
|
- [ ] Specific, actionable challenges
|
|
- [ ] Hints without full solutions
|
|
- [ ] Real world applications
|
|
- [ ] Connection to other projects
|
|
|
|
### General
|
|
- [ ] No em dashes
|
|
- [ ] Minimal "it's not X, it's Y" patterns
|
|
- [ ] Inconsistent hyphenation (like a human)
|
|
- [ ] Concrete examples, not abstractions
|
|
- [ ] Code examples are real, not toys
|
|
- [ ] Diagrams where helpful
|
|
- [ ] Links work
|
|
- [ ] Formatting is consistent
|
|
|
|
## Examples
|
|
|
|
Good examples to reference:
|
|
|
|
- **PROJECTS/advanced/bug-bounty-platform/learn/** - Comprehensive, well structured
|
|
- **PROJECTS/advanced/api-rate-limiter/learn/** - Good technical depth
|
|
|
|
These aren't perfect but they're solid templates to learn from.
|
|
|
|
## Getting Help
|
|
|
|
Questions about writing learn/ docs?
|
|
|
|
1. Look at existing examples
|
|
2. Ask in discussions
|
|
3. Draft one file and get feedback before doing all five
|
|
4. Iterate based on feedback
|
|
|
|
## Contributing Improvements
|
|
|
|
Found ways to improve these templates?
|
|
|
|
1. Make changes to `.github/learn-folder-template/`
|
|
2. Submit PR with explanation
|
|
3. Update this README if structure changes
|
|
|
|
The templates should evolve as we learn what works best.
|