582 lines
12 KiB
Markdown
582 lines
12 KiB
Markdown
---
|
|
name: technical-tutorials
|
|
description: When the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial."
|
|
risk: unknown
|
|
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/technical-tutorials
|
|
source_repo: jonathimer/devmarketing-skills
|
|
source_type: community
|
|
date_added: 2026-07-01
|
|
license: MIT
|
|
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
|
|
---
|
|
|
|
# Technical Tutorials
|
|
## When to Use
|
|
|
|
Use this skill when you need when the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial.".
|
|
|
|
|
|
This skill helps you create step-by-step tutorials that actually work. Covers prerequisite handling, progressive complexity, troubleshooting sections, and creating those satisfying "it works!" moments.
|
|
|
|
---
|
|
|
|
## Before You Start
|
|
|
|
**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:
|
|
|
|
- Developer skill level (beginner, intermediate, senior)
|
|
- Tech stack familiarity (what can you assume they know?)
|
|
- Environment (macOS, Linux, Windows, cloud)
|
|
- Why they're learning (job, side project, curiosity)
|
|
|
|
If the context file doesn't exist, run the `developer-audience-context` skill first.
|
|
|
|
---
|
|
|
|
## Tutorial Types
|
|
|
|
| Type | Length | Purpose | Example |
|
|
|------|--------|---------|---------|
|
|
| **Quickstart** | 5-10 min | First success ASAP | "Make your first API call" |
|
|
| **Tutorial** | 20-45 min | Learn a concept deeply | "Build a REST API with Node.js" |
|
|
| **Workshop** | 1-3 hours | Comprehensive project | "Build a full-stack app" |
|
|
| **Code walkthrough** | Varies | Explain existing code | "Understanding our SDK architecture" |
|
|
|
|
---
|
|
|
|
## The Tutorial Structure
|
|
|
|
### Anatomy of a Great Tutorial
|
|
|
|
```
|
|
1. Title & Meta
|
|
- What you'll build
|
|
- Time estimate
|
|
- Prerequisites
|
|
|
|
2. Overview
|
|
- What you'll learn
|
|
- Final result preview
|
|
|
|
3. Prerequisites Check
|
|
- Environment setup
|
|
- Verification commands
|
|
|
|
4. The Build (Progressive Steps)
|
|
- Step 1: Simplest foundation
|
|
- Step 2: Add one concept
|
|
- Step 3: Add complexity
|
|
- [Checkpoint: "It works!" moment]
|
|
- Step 4: Continue building
|
|
- ...
|
|
- [Final checkpoint]
|
|
|
|
5. What You Built
|
|
- Recap
|
|
- Complete code
|
|
|
|
6. Troubleshooting
|
|
- Common errors
|
|
- Debugging tips
|
|
|
|
7. Next Steps
|
|
- Where to go from here
|
|
- Related tutorials
|
|
```
|
|
|
|
---
|
|
|
|
## Prerequisites Handling
|
|
|
|
### The Prerequisites Section
|
|
|
|
Be explicit. Don't make developers guess what they need.
|
|
|
|
```markdown
|
|
## Prerequisites
|
|
|
|
Before starting, make sure you have:
|
|
|
|
| Requirement | Version | Check Command |
|
|
|-------------|---------|---------------|
|
|
| Node.js | 18+ | `node --version` |
|
|
| npm | 9+ | `npm --version` |
|
|
| Git | Any | `git --version` |
|
|
|
|
You should also be comfortable with:
|
|
- Basic JavaScript (variables, functions, async/await)
|
|
- Command line basics (cd, mkdir, running commands)
|
|
- REST API concepts (HTTP methods, JSON)
|
|
|
|
**New to any of these?** Check out [link to prerequisite tutorial].
|
|
```
|
|
|
|
### Environment Setup Section
|
|
|
|
Make setup foolproof:
|
|
|
|
```markdown
|
|
## Setting Up Your Environment
|
|
|
|
### 1. Create Project Directory
|
|
|
|
\`\`\`bash
|
|
mkdir my-awesome-project
|
|
cd my-awesome-project
|
|
\`\`\`
|
|
|
|
### 2. Initialize the Project
|
|
|
|
\`\`\`bash
|
|
npm init -y
|
|
\`\`\`
|
|
|
|
You should see output like:
|
|
\`\`\`json
|
|
{
|
|
"name": "my-awesome-project",
|
|
"version": "1.0.0",
|
|
...
|
|
}
|
|
\`\`\`
|
|
|
|
### 3. Install Dependencies
|
|
|
|
\`\`\`bash
|
|
npm install express dotenv
|
|
\`\`\`
|
|
|
|
### 4. Verify Installation
|
|
|
|
\`\`\`bash
|
|
node -e "require('express'); console.log('Express installed!')"
|
|
\`\`\`
|
|
|
|
Expected output: `Express installed!`
|
|
```
|
|
|
|
---
|
|
|
|
## Progressive Complexity
|
|
|
|
### The Layer Cake Approach
|
|
|
|
Build up in understandable layers:
|
|
|
|
| Layer | What It Does | Example |
|
|
|-------|--------------|---------|
|
|
| **1. Skeleton** | Minimum viable code that runs | "Hello World" server |
|
|
| **2. Core feature** | Primary functionality | Add one API endpoint |
|
|
| **3. Real data** | Replace hardcoded values | Connect to database |
|
|
| **4. Error handling** | Production-ready patterns | Add try/catch, validation |
|
|
| **5. Polish** | Nice-to-haves | Logging, config, tests |
|
|
|
|
### Show Progress, Not Perfection
|
|
|
|
**Wrong approach** (overwhelming):
|
|
```javascript
|
|
// Here's the complete file with everything
|
|
const express = require('express');
|
|
const { Pool } = require('pg');
|
|
const helmet = require('helmet');
|
|
const rateLimit = require('express-rate-limit');
|
|
const winston = require('winston');
|
|
// ... 200 more lines
|
|
```
|
|
|
|
**Right approach** (progressive):
|
|
|
|
**Step 1: Basic server**
|
|
```javascript
|
|
const express = require('express');
|
|
const app = express();
|
|
|
|
app.get('/', (req, res) => {
|
|
res.send('Hello World!');
|
|
});
|
|
|
|
app.listen(3000, () => {
|
|
console.log('Server running on http://localhost:3000');
|
|
});
|
|
```
|
|
|
|
**Step 2: Add your first route**
|
|
```javascript
|
|
// Add this below your existing route
|
|
app.get('/api/users', (req, res) => {
|
|
res.json([{ id: 1, name: 'Jane' }]);
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Copy-Paste Friendly Code
|
|
|
|
### The Copy-Paste Checklist
|
|
|
|
Every code block must pass these tests:
|
|
|
|
| Test | How to Verify |
|
|
|------|---------------|
|
|
| **Runs standalone** | Copy into new file, execute, it works |
|
|
| **Imports included** | All `require`/`import` statements present |
|
|
| **No undefined variables** | No references to code from other steps without showing it |
|
|
| **Environment agnostic** | Works on Mac/Linux/Windows |
|
|
| **Comments explain why** | Not what (code shows what), but why |
|
|
|
|
### Code Block Patterns
|
|
|
|
**File context is critical:**
|
|
|
|
```javascript
|
|
// server.js - Add this to your existing file
|
|
const rateLimit = require('express-rate-limit');
|
|
|
|
// Add this BEFORE your routes
|
|
const limiter = rateLimit({
|
|
windowMs: 15 * 60 * 1000, // 15 minutes
|
|
max: 100 // limit each IP to 100 requests per window
|
|
});
|
|
|
|
app.use(limiter);
|
|
```
|
|
|
|
**Show file structure:**
|
|
|
|
```
|
|
my-project/
|
|
├── src/
|
|
│ ├── index.js ← You're editing this
|
|
│ ├── routes/
|
|
│ │ └── users.js
|
|
│ └── db/
|
|
│ └── connection.js
|
|
├── package.json
|
|
└── .env
|
|
```
|
|
|
|
**Highlight changes in context:**
|
|
|
|
```javascript
|
|
// src/index.js
|
|
const express = require('express');
|
|
const app = express();
|
|
|
|
// ✅ ADD THIS: Import your new route
|
|
const userRoutes = require('./routes/users');
|
|
|
|
// ✅ ADD THIS: Use the route
|
|
app.use('/api/users', userRoutes);
|
|
|
|
app.listen(3000);
|
|
```
|
|
|
|
---
|
|
|
|
## "It Works!" Moments
|
|
|
|
### Checkpoints Create Motivation
|
|
|
|
Every 3-5 steps, give developers a win:
|
|
|
|
```markdown
|
|
## Checkpoint: Test Your API
|
|
|
|
Let's make sure everything works before continuing.
|
|
|
|
**Start your server:**
|
|
\`\`\`bash
|
|
node server.js
|
|
\`\`\`
|
|
|
|
**In a new terminal, test the endpoint:**
|
|
\`\`\`bash
|
|
curl http://localhost:3000/api/users
|
|
\`\`\`
|
|
|
|
**You should see:**
|
|
\`\`\`json
|
|
[{"id": 1, "name": "Jane"}]
|
|
\`\`\`
|
|
|
|
🎉 **It works!** Your API is returning data.
|
|
|
|
If you don't see this output, check the [Troubleshooting](#troubleshooting) section.
|
|
```
|
|
|
|
### Visual Confirmation
|
|
|
|
When possible, show what success looks like:
|
|
|
|
| Output Type | How to Show |
|
|
|-------------|-------------|
|
|
| **Terminal output** | Code block with expected text |
|
|
| **Browser result** | Screenshot or description |
|
|
| **API response** | Formatted JSON |
|
|
| **Logs** | Code block with log output |
|
|
|
|
---
|
|
|
|
## Troubleshooting Sections
|
|
|
|
### Common Error Template
|
|
|
|
```markdown
|
|
## Troubleshooting
|
|
|
|
### "Error: Cannot find module 'express'"
|
|
|
|
**Cause:** Dependencies weren't installed.
|
|
|
|
**Fix:**
|
|
\`\`\`bash
|
|
npm install
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
### "EADDRINUSE: address already in use :::3000"
|
|
|
|
**Cause:** Another process is using port 3000.
|
|
|
|
**Fix (macOS/Linux):**
|
|
\`\`\`bash
|
|
# Find the process
|
|
lsof -i :3000
|
|
|
|
# Kill it (replace PID with actual number)
|
|
kill -9 PID
|
|
\`\`\`
|
|
|
|
**Or use a different port:**
|
|
\`\`\`javascript
|
|
app.listen(process.env.PORT || 3001);
|
|
\`\`\`
|
|
|
|
---
|
|
|
|
### "SyntaxError: Unexpected token"
|
|
|
|
**Cause:** Likely a typo or missing bracket.
|
|
|
|
**Debug steps:**
|
|
1. Check the line number in the error
|
|
2. Look for missing `,`, `}`, or `)`
|
|
3. Verify all strings are closed with matching quotes
|
|
```
|
|
|
|
### Proactive Error Prevention
|
|
|
|
Add warnings before common pitfalls:
|
|
|
|
```markdown
|
|
⚠️ **Windows users:** Use `set` instead of `export`:
|
|
\`\`\`bash
|
|
# macOS/Linux
|
|
export API_KEY=your_key
|
|
|
|
# Windows Command Prompt
|
|
set API_KEY=your_key
|
|
|
|
# Windows PowerShell
|
|
$env:API_KEY = Read-Host -AsSecureString "API key"
|
|
\`\`\`
|
|
```
|
|
|
|
---
|
|
|
|
## Tutorial Templates
|
|
|
|
### Quickstart Template (5-10 minutes)
|
|
|
|
```markdown
|
|
# [Product] Quickstart: [What You'll Do] in 5 Minutes
|
|
|
|
Get [specific outcome] in under 5 minutes.
|
|
|
|
## Prerequisites
|
|
|
|
- [Requirement 1]
|
|
- [Requirement 2]
|
|
|
|
## Step 1: Install
|
|
|
|
\`\`\`bash
|
|
npm install your-package
|
|
\`\`\`
|
|
|
|
## Step 2: Configure
|
|
|
|
Create a `.env` file:
|
|
\`\`\`
|
|
API_KEY=your_key_here
|
|
\`\`\`
|
|
|
|
## Step 3: Write Code
|
|
|
|
Create `index.js`:
|
|
\`\`\`javascript
|
|
// Complete, working code
|
|
\`\`\`
|
|
|
|
## Step 4: Run It
|
|
|
|
\`\`\`bash
|
|
node index.js
|
|
\`\`\`
|
|
|
|
Expected output:
|
|
\`\`\`
|
|
[Output here]
|
|
\`\`\`
|
|
|
|
## 🎉 You Did It!
|
|
|
|
You just [accomplished thing].
|
|
|
|
**Next steps:**
|
|
- [Link to full tutorial]
|
|
- [Link to API docs]
|
|
- [Link to examples repo]
|
|
```
|
|
|
|
### Full Tutorial Template (20-45 minutes)
|
|
|
|
```markdown
|
|
# Build a [Thing] with [Technology]
|
|
|
|
Learn how to [outcome] by building [specific project].
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Time** | 30 minutes |
|
|
| **Level** | Intermediate |
|
|
| **Prerequisites** | Node.js 18+, basic JavaScript |
|
|
|
|
## What You'll Build
|
|
|
|
[Screenshot or diagram of final result]
|
|
|
|
By the end, you'll have:
|
|
- ✅ [Capability 1]
|
|
- ✅ [Capability 2]
|
|
- ✅ [Capability 3]
|
|
|
|
## Prerequisites
|
|
|
|
### Required Software
|
|
|
|
| Tool | Version | Verify |
|
|
|------|---------|--------|
|
|
| Node.js | 18+ | `node -v` |
|
|
|
|
### Required Knowledge
|
|
|
|
- [Concept 1] — [link to learn]
|
|
- [Concept 2] — [link to learn]
|
|
|
|
## Step 1: Project Setup
|
|
|
|
[Setup instructions with verification]
|
|
|
|
**Checkpoint:** You should see `[expected output]`.
|
|
|
|
## Step 2: [First Feature]
|
|
|
|
[Instructions]
|
|
|
|
**Checkpoint:** Test with `[command]`.
|
|
|
|
## Step 3: [Second Feature]
|
|
|
|
[Instructions]
|
|
|
|
## Step 4: [Third Feature]
|
|
|
|
[Instructions]
|
|
|
|
**Checkpoint:** Your app should now [do thing].
|
|
|
|
## Complete Code
|
|
|
|
Here's everything together:
|
|
|
|
\`\`\`javascript
|
|
// Full final code
|
|
\`\`\`
|
|
|
|
## Troubleshooting
|
|
|
|
### [Common Error 1]
|
|
[Solution]
|
|
|
|
### [Common Error 2]
|
|
[Solution]
|
|
|
|
## What You Learned
|
|
|
|
- [Key concept 1]
|
|
- [Key concept 2]
|
|
- [Key concept 3]
|
|
|
|
## Next Steps
|
|
|
|
- **Go deeper:** [Link to advanced tutorial]
|
|
- **Explore:** [Link to related feature]
|
|
- **Get help:** [Link to Discord/community]
|
|
```
|
|
|
|
---
|
|
|
|
## Quality Checklist
|
|
|
|
Before publishing, verify:
|
|
|
|
### Code Quality
|
|
- [ ] Every code block runs without modification
|
|
- [ ] All imports/requires are included
|
|
- [ ] Expected output is shown
|
|
- [ ] Error handling is included
|
|
- [ ] Environment variables use `.env` pattern
|
|
|
|
### Structure Quality
|
|
- [ ] Prerequisites are explicit
|
|
- [ ] Time estimate is accurate (test it!)
|
|
- [ ] Checkpoints every 3-5 steps
|
|
- [ ] Final complete code is provided
|
|
- [ ] Troubleshooting covers likely errors
|
|
|
|
### Accessibility
|
|
- [ ] Works on Mac, Linux, AND Windows
|
|
- [ ] Commands work in bash/zsh/PowerShell
|
|
- [ ] File paths use correct separators
|
|
- [ ] No assumptions about installed tools
|
|
|
|
---
|
|
|
|
## Tools
|
|
|
|
| Tool | Use Case |
|
|
|------|----------|
|
|
| **[Octolens](https://octolens.com)** | Find common questions and errors developers encounter. Monitor Stack Overflow and GitHub issues for troubleshooting content. |
|
|
| **Replit/CodeSandbox** | Embed runnable examples |
|
|
| **Carbon/Ray.so** | Beautiful code screenshots |
|
|
| **Excalidraw** | Architecture diagrams |
|
|
| **Terminalizer** | Record terminal sessions |
|
|
| **Loom** | Quick video supplements |
|
|
|
|
---
|
|
|
|
## Related Skills
|
|
|
|
- `developer-audience-context` — Understand skill level and environment
|
|
- `devrel-content` — General technical writing principles
|
|
- `developer-onboarding` — Optimize time to first success
|
|
- `developer-seo` — Get tutorials found via search
|
|
|
|
## Limitations
|
|
|
|
- Use this skill only when the task clearly matches its upstream source and local project context.
|
|
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
|
|
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
|