hackforla
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
- [x] Beginner
- [x] 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
- [ ] Title & Overview: Clear, descriptive tutorial name + short overview of what it covers.
- [ ] Purpose: Why the tutorial matters, what problem it solves, or what skills it teaches.
- [ ] Prerequisites: List of assumed knowledge or tools students should already have.
- [ ] Setup Instructions: Step-by-step guide for installing or preparing required tools/software.
- [ ] Core Concepts: Break tutorial into sections with explanations and examples.
- [ ] Hands-On Lessons/Exercises: Provide links, files, or in-line instructions for practice.
- [ ] Best Practices & Tips: Highlight common pitfalls, debugging help, or efficiency tricks.
- [ ] Examples: Any projects that we have done that illustrate this. If we don't have any, you may wish to make a sample, but it may not be required.
- [ ] Additional Resources: Curated links, videos, and references for further study.
- [ ] Contributors: Credit authors and collaborators.
- [ ] Issues Referenced: Link back to GitHub issues (if tutorial originated from repo discussions).
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
- [ ] Title & Overview: Clear, descriptive tutorial name + summary of why this topic is at the intermediate level.
- [ ] Purpose: Explain the value of this tutorial — what deeper skills or workflows learners will gain beyond beginner level.
- [ ] Prerequisites: Specify assumed knowledge, tools, and concepts (e.g., Python basics, Git, data structures).
- [ ] Setup Instructions: Step-by-step environment prep (repos, libraries, datasets, APIs, accounts).
- [ ] Core Concepts: Explain the intermediate theory/frameworks behind the tutorial, not just “how” but also “why.”
- [ ] Step-by-Step Walkthrough: A guided example or pipeline that ties the core concepts together.
- [ ] Hands-On Exercises: Independent practice tasks, including stretch goals or variations on the walkthrough.
- [ ] Common Pitfalls & Troubleshooting: Document frequent errors, debugging strategies, or misconceptions.
- [ ] Best Practices: Efficiency tricks, sustainability practices, or standards relevant to the workflow.
- [ ] Reflection & Discussion Prompts: Encourage learners to connect tutorial lessons to real-world civic tech or professional applications.
- [ ] Next Steps / Advanced Extensions: Point to advanced tutorials, related skills, or scaling challenges.
- [ ] Glossary / Key Terms: Define specialized terminology introduced in the tutorial.
- [ ] Additional Resources: Curated links to docs, videos, and advanced reading.
- [ ] Contributors: Credit authors, reviewers, and maintainers.
- [ ] Issues Referenced: Link back to GitHub issues (if tutorial originated from repo discussions).
Template View
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).
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 will create a checklist for assignees to self review code submissions
@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