K
K12worX Education501(c)(3) Public Charity
Jamboree

Learning Guide Status

Overview

This comprehensive learning guide helps high school students with minimal HTML/CSS background learn to understand, run, and contribute to the K12worX NextJS website.

Total Structure: 10 sections, 47 planned markdown files
Files Created: 17 core files (Sections 00-02 complete)
Remaining: Section templates created, ready for expansion

✅ COMPLETED SECTIONS (17 files)

Main Guide

  • [✅] README.md - Complete learning path overview with all sections outlined

Section 00: Prerequisites (5 files) - COMPLETE ✅

  • [✅] 00-prerequisites/README.md - Section overview
  • [✅] 00-prerequisites/installing-node.md - Node.js & npm installation
  • [✅] 00-prerequisites/installing-vscode.md - VS Code setup with extensions
  • [✅] 00-prerequisites/installing-git.md - Git installation & configuration
  • [✅] 00-prerequisites/command-line-basics.md - Terminal essentials

Section 01: Understanding Basics (6 files) - COMPLETE ✅

  • [✅] 01-understanding-basics/README.md - Section overview
  • [✅] 01-understanding-basics/html-css-refresher.md - HTML/CSS fundamentals
  • [✅] 01-understanding-basics/what-is-nextjs.md - Next.js framework explanation
  • [✅] 01-understanding-basics/what-is-typescript.md - TypeScript basics
  • [✅] 01-understanding-basics/what-is-react.md - React components & JSX
  • [✅] 01-understanding-basics/what-is-tailwind.md - Tailwind CSS utility classes

Section 02: Getting Started (5 files) - COMPLETE ✅

  • [✅] 02-getting-started/README.md - Section overview
  • [✅] 02-getting-started/cloning-the-repo.md - Git clone instructions
  • [✅] 02-getting-started/running-dev-server.md - npm install & npm run dev
  • [✅] 02-getting-started/exploring-localhost.md - Understanding localhost:3000
  • [✅] 02-getting-started/your-first-code-change.md - First hands-on edit

📋 SECTIONS READY FOR EXPANSION (30 files)

The following sections have their folder structure created and are ready for content. Each section outline below shows the planned content.

Section 03: Understanding Structure (5 files)

Purpose: Learn how the App Router, pages, components, and layouts work

Planned files:

  • README.md - Section overview
  • app-router-explained.md - File-based routing system
  • pages-and-routing.md - How folders become URLs
  • components-explained.md - Reusable UI pieces
  • layouts-explained.md - DefaultLayout, ArticleLayout, LandingLayout

Key Concepts to Cover:

  • File structure → URL mapping
  • Special file names (page.tsx, layout.tsx)
  • Component composition
  • Props and children pattern

Section 04: Reading Code (5 files)

Purpose: Guided walkthroughs of actual codebase files

Planned files:

  • README.md - Section overview
  • reading-homepage.md - Line-by-line app/page.tsx analysis
  • reading-header.md - components/layout/Header.tsx walkthrough
  • reading-navigation.md - Navigation component with navItems array
  • understanding-props.md - How data flows through components

Key Files to Analyze:

  • app/page.tsx - Homepage structure
  • components/layout/Header.tsx - Simple component
  • components/layout/Navigation.tsx - Data-driven component
  • components/layout/DefaultLayout.tsx - Layout composition

Section 05: Styling Basics (4 files)

Purpose: Master Tailwind CSS for styling

Planned files:

  • README.md - Section overview
  • tailwind-classes.md - Common utility classes reference
  • responsive-design.md - Mobile-first with md:, lg: prefixes
  • customizing-colors.md - Using theme colors from tailwind.config.ts

Key Concepts:

  • Spacing (p-, m-, gap-*)
  • Colors (bg-, text-)
  • Typography (text-, font-)
  • Responsive breakpoints
  • Hover and interactive states

Section 06: Making Changes (5 files)

Purpose: Practice making real contributions

Planned files:

  • README.md - Section overview
  • changing-text-content.md - Safe first edits
  • adding-new-links.md - Update navItems in Navigation.tsx
  • modifying-styles.md - Change colors, sizes, spacing
  • testing-your-changes.md - What to check before committing

Practical Exercises:

  • Update homepage text
  • Add navigation item
  • Change button colors
  • Adjust spacing and layout
  • Test responsive behavior

Section 07: Git Basics (5 files)

Purpose: Learn version control workflow

Planned files:

  • README.md - Section overview
  • git-workflow.md - Branch → Change → Commit → Push → PR
  • creating-branches.md - git checkout -b feature-name
  • making-commits.md - git add, git commit with good messages
  • understanding-pull-requests.md - Creating and reviewing PRs

Key Commands:

  • git status - See what changed
  • git add - Stage changes
  • git commit - Save snapshot
  • git push - Upload to GitHub
  • git checkout -b - Create branch

Section 08: Advanced Topics (5 files)

Purpose: Build more complex features

Planned files:

  • README.md - Section overview
  • creating-new-pages.md - Add new routes with page.tsx
  • building-components.md - Create reusable components with TypeScript
  • working-with-forms.md - Understanding ContactForm.tsx
  • understanding-typescript-types.md - Interfaces and prop types

Skills to Learn:

  • Creating app/newpage/page.tsx
  • Component with TypeScript interface
  • useState for form handling
  • Client vs server components

Section 09: Troubleshooting (4 files)

Purpose: Solve common problems independently

Planned files:

  • README.md - Section overview
  • common-errors.md - Port in use, module not found, syntax errors
  • debugging-tips.md - Reading errors, console.log, DevTools
  • getting-help.md - Where to ask, how to describe problems

Common Issues:

  • Port 3000 already in use
  • MODULE_NOT_FOUND errors
  • TypeScript type errors
  • Hot reload not working
  • Build failures

Section 10: Reference (5 files)

Purpose: Quick reference materials

Planned files:

  • README.md - Section overview
  • glossary.md - Alphabetical definitions of technical terms
  • useful-commands.md - npm, git, terminal command reference
  • external-resources.md - Curated links with context
  • codebase-map.md - Visual diagram of file structure

Reference Content:

  • Technical vocabulary
  • Command cheat sheets
  • Links to documentation
  • File structure diagram
  • Quick troubleshooting index

Content Guidelines

All completed sections follow these principles:

Writing Style

  • Clear, beginner-friendly language
  • Define technical terms on first use
  • Real-world examples from K12worX codebase
  • Mix of tutorial, reference, and task-based content

Structure

  • Each section has README.md overview
  • Progressive difficulty
  • Hands-on exercises embedded
  • Success checkpoints
  • "Try This" challenges

External Resources

  • Links to official documentation
  • Context explaining what each resource is
  • When to use each resource
  • Students kept "under our guidance"
  • Links between files (← Previous | Next →)
  • Back to section README
  • Quick reference sections

Expanding the Guide

To complete the remaining sections (03-10), follow the patterns established in sections 00-02:

Template Structure for Each File

# [Topic Title]

Brief introduction explaining what this covers and why it matters.

## What You'll Learn

- Bullet points of key concepts

## [Main Content Sections]

Progressive sections with:
- Clear explanations
- Code examples from our codebase
- "Try This" exercises
- Common mistakes callouts

## Troubleshooting

Common issues specific to this topic

## Tips for [Topic]

Best practices and helpful hints

## External Resources

Curated links with:
- What it is
- When to use it
- How long it takes

## Quick Reference

Commands/concepts summarized

## Quick Links

- [← Previous Topic](previous.md)
- [Next Topic →](next.md)

Key Features of Completed Sections

Section 00: Prerequisites

  • Platform-specific instructions (Mac/Windows)
  • Verification commands
  • Troubleshooting for installation issues
  • VS Code extensions setup
  • Command line practice exercises

Section 01: Understanding Basics

  • HTML/CSS refresher with external resources
  • Technology overviews (Next.js, TypeScript, React, Tailwind)
  • Comparison tables (traditional vs modern approaches)
  • "What you don't need to know" sections
  • Interactive learning resource links

Section 02: Getting Started

  • Step-by-step setup instructions
  • git clone walkthrough
  • npm install explanation
  • Dev server startup guide
  • First code change exercise with purposeful errors

Student Learning Path

The completed sections guide students through:

Week 1 (Sections 00-01):

  • Install all tools
  • Understand fundamental concepts
  • Review HTML/CSS basics

Week 2 (Section 02):

  • Clone repository
  • Run dev server
  • Make first code change
  • Experience hot reload

Weeks 3-4 (Sections 03-06):

  • Understand codebase structure
  • Read and analyze code
  • Practice making changes
  • Master Tailwind styling

Weeks 5-6 (Sections 07-08):

  • Learn Git workflow
  • Create branches and commits
  • Build new features
  • Advanced TypeScript

Ongoing (Sections 09-10):

  • Reference materials
  • Troubleshooting guide
  • Independent problem-solving

Success Metrics

A student completing this guide should be able to:

  1. ✅ Set up development environment independently
  2. ✅ Run the website locally
  3. ✅ Navigate the codebase confidently
  4. ✅ Understand pages, components, and layouts
  5. ✅ Make content and styling changes
  6. ✅ Use Tailwind CSS effectively
  7. ✅ Create new pages using existing layouts
  8. ✅ Follow Git workflow for contributions
  9. ✅ Debug common errors independently
  10. ✅ Know where to find help when stuck

Next Steps for Development

To complete the learning guide:

  1. Expand Section 03 - Understanding Structure files based on completed patterns
  2. Expand Section 04 - Code reading guides with actual file walkthroughs
  3. Expand Section 05 - Tailwind styling practice exercises
  4. Expand Section 06 - Progressive change-making tutorials
  5. Expand Section 07 - Git workflow with visual diagrams
  6. Expand Section 08 - Advanced topics for skill building
  7. Expand Section 09 - Troubleshooting database with solutions
  8. Expand Section 10 - Comprehensive reference materials

Each section follows the established patterns for consistency and quality.

Last Updated: 2025-12-10
Status: Core sections complete (00-02), structure ready for expansion (03-10)
Total Progress: 17/47 files (36% complete, all foundational work done)