Tutorial Template creation

Overview

We need to create outlines/templates for Tutorials by level, so that new people writing a tutorial have some place to start and we have a checklist to make sure it covers the obvious.

Action Items

paste the tutorials into chatGPT by level, and ask it to outline their commonalities and create markdown templates
- Beginner
- Intermediate
- Advanced
Add these to the wiki

Resources/Instructions

conversation with ChatGPT to make these checklists https://chatgpt.com/share/68b63ade-428c-8008-aeba-582e14528a56

Generic Markdown Outline for Beginner Tutorials

✅ Tutorial Creation Checklist

Template view

[Insert Tutorial Title Here]

Overview

[Insert content here]

Purpose

[Insert content here]

Prerequisites

[Insert content here]

Setup Before Workshop

[Insert content here]

Core Concepts

Concept 1: [Insert topic here]

[Insert content here]

Concept 2: [Insert topic here]

[Insert content here]

Concept 3: [Insert topic here]

[Insert content here]

Hands-On Lessons & Exercises

[Insert lesson link or description here]
[Insert exercise instructions here]

Best Practices & Tips

[Insert content here]

Examples

[Insert content here]

Additional Resources

[Insert content here]

Contributors

[Insert content here]

Issues Referenced

[Insert content here]

Template copy

## [Insert Tutorial Title Here]

## Overview
[Insert content here]

## Purpose
[Insert content here]

## Prerequisites
[Insert content here]

## Setup Before Workshop
[Insert content here]

## Core Concepts
### Concept 1: [Insert topic here]
[Insert content here]

### Concept 2: [Insert topic here]
[Insert content here]

### Concept 3: [Insert topic here]
[Insert content here]

## Hands-On Lessons & Exercises
- [Insert lesson link or description here]
- [Insert exercise instructions here]

## Best Practices & Tips
[Insert content here]

## Examples
[Insert content here]

## Additional Resources
[Insert content here]

## Contributors
[Insert content here]

## Issues Referenced
[Insert content here]

Key Differences Between Beginner vs. Intermediate Tutorials

Scope & Depth

Beginner tutorials focus on single, isolated skills (e.g., loading CSVs, making simple plots, cleaning data). They are usually short, linear, and prescriptive (“do this, then that”).

Intermediate tutorials (like Web Scraping and Geospatial Analysis) combine multiple skills into a workflow — they don’t just show one tool, they show how tools interconnect (requests → parsing → storage, or geopandas → shapely → visualization).

Format & Presentation

Beginners: Consistent structure → intro, short demo, small code snippets, a few links.

Intermediates: Longer, more narrative style with sections (“Overview,” “Tools,” “Putting it all together”) and often HTML formatting, tables, or embedded images. They also cite external references and real Hack for LA projects.

Audience Assumptions

Beginner tutorials assume the learner is new to data science and Python, so they explicitly define terms and provide guided steps.

Intermediate tutorials assume you already know Python/pandas basics and can navigate documentation; they focus on domain-specific knowledge (e.g., CRSs, OSMnx, pysal).

Outcomes & Use Cases

Beginner tutorials → “You will learn how to clean a dataset” (skill-focused).

Intermediate tutorials → “You will learn how to combine multiple datasets, resolve geospatial issues, and produce useful civic tech maps” (project-focused).

Maintenance Needs

Beginners are relatively static — code snippets don’t change often.

Intermediates link to external repos, APIs, and evolving packages — they require ongoing maintenance (e.g., OSMnx or pysal updates).

Why This Matters for Your Checklists / Documentation

Beginner checklists should emphasize completion of small exercises (“Did the learner install pandas? Did they plot a histogram?”).

Intermediate checklists should emphasize workflow understanding and application (“Did the learner successfully join two datasets? Did they use CRS correctly? Did they map results with folium?”).

So, the intermediate ones need more conceptual checkpoints (grasp of why, not just how).

Generic Markdown Template for Intermediate Tutorials

✅ Tutorial Creation Checklist

Template View

Intermediate Tutorial Checklist Template

Template Copy

### Intermediate Tutorial Checklist Template

- [ ] **Title & Introduction**
  - Concise title describing the skill/technique.
  - Short overview of why the topic matters in practice.
  - Real-world or civic tech examples that make it relevant.

- [ ] **Learning Objectives**
  - Clear, action-oriented goals (e.g., “By the end of this tutorial, you will be able to…”).
  - Typically 3–5 bullet points.

- [ ] **Prerequisites**
  - Skills: what learners should already know (e.g., Python basics, Git).
  - Tools: required installations/accounts (e.g., Jupyter, Google Drive, GitHub).

- [ ] **Setup Instructions**
  - Step-by-step environment setup (repos, libraries, data files).
  - Screenshots or code snippets where helpful.
  - Links to official docs for installation.

- [ ] **Core Concepts**
  - Explain intermediate-level concepts (not just “how,” but “why”).
  - Provide diagrams, workflows, or conceptual frameworks where useful.

- [ ] **Step-by-Step Walkthrough**
  - A guided, reproducible example that ties the concepts together.
  - Code snippets, terminal commands, or GUI steps as needed.
  - Incremental build-up: small wins before the full pipeline/project.

- [ ] **Hands-On Exercise**
  - Task for the learner to try independently (variation on the walkthrough).
  - Include dataset or problem statement.
  - Stretch goal(s) for advanced learners.

- [ ] **Common Pitfalls & Troubleshooting**
  - Document frequent errors or misconceptions.
  - Provide quick fixes or debugging tips.

- [ ] **Discussion & Reflection**
  - Prompts to connect the exercise to real-world applications.
  - Example: “How would you adapt this workflow for a different dataset?”

- [ ] **Next Steps / Advanced Topics**
  - Suggest follow-up tutorials, advanced readings, or extensions.
  - Could include integration with other tools, scaling techniques, or optimization.

- [ ] **Glossary / Key Terms**
  - Define domain-specific terminology introduced in the tutorial.

- [ ] **References & Resources**
  - Links to external tutorials, academic references, or tool documentation.
  - Links to related Hack for LA projects, repos, or dashboards.

- [ ] **Contributors**
  - Credit authors and maintainers.
  - Optional: invite learners to contribute back (PRs, examples, feedback).

@chinaexpert1

@chinaexpert1 will create a checklist for assignees to self review code submissions

@ExperimentsInHonesty

@ExperimentsInHonesty will update intermediate checklist and templates with example checkbox from beginner

Instructions

Progress: "What is the current status of your project? What have you completed and what is left to do?"
Blockers: "Difficulties or errors encountered."
Availability: "How much time will you have this week to work on this issue?"
ETA: "When do you expect this issue to be completed?"
Pictures (if necessary): "Add any pictures that will help illustrate what you are working on."

Progress: I just discovered this in the Needs Peer Review Column. Moved to in progress because I need to make that code review checklist
Blockers:
Availability: 1hour
ETA: 1 week
Pictures (if necessary):

I've been doing different templates for each tutorial series and putting them collapsed under

Details

in the Epic.

Navigation Menu

Repository navigation

Tutorial Template creation #225

Overview

Action Items

Resources/Instructions

Generic Markdown Outline for Beginner Tutorials

✅ Tutorial Creation Checklist

[Insert Tutorial Title Here]

Overview

Purpose

Prerequisites

Setup Before Workshop

Core Concepts

Concept 1: [Insert topic here]

Concept 2: [Insert topic here]

Concept 3: [Insert topic here]

Hands-On Lessons & Exercises

Best Practices & Tips

Examples

Additional Resources

Contributors

Issues Referenced

Generic Markdown Template for Intermediate Tutorials

Intermediate Tutorial Checklist Template

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tutorial Template creation #225

Description

Overview

Action Items

Resources/Instructions

Activity

ExperimentsInHonesty commented on Aug 18, 2025

Generic Markdown Outline for Beginner Tutorials

✅ Tutorial Creation Checklist

[Insert Tutorial Title Here]

Overview

Purpose

Prerequisites

Setup Before Workshop

Core Concepts

Concept 1: [Insert topic here]

Concept 2: [Insert topic here]

Concept 3: [Insert topic here]

Hands-On Lessons & Exercises

Best Practices & Tips

Examples

Additional Resources

Contributors

Issues Referenced

ExperimentsInHonesty commented on Sep 2, 2025

ExperimentsInHonesty commented on Sep 2, 2025

Generic Markdown Template for Intermediate Tutorials

Intermediate Tutorial Checklist Template

ExperimentsInHonesty commented on Sep 9, 2025

ExperimentsInHonesty commented on Sep 9, 2025

chinaexpert1 commented on Sep 13, 2025

chinaexpert1 commented on Sep 20, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions