---
name: tutorial
description: Write step-by-step tutorials with clear instructions, screenshots, and troubleshooting tips.
---

# Skill: Tutorial

Step-by-step instructional guides for gauravtiwari.org.

## Specifications

| Attribute | Value |
|-----------|-------|
| Default length | 2000+ words |
| Steps | Numbered, with expected outcomes |
| Prerequisites | Required section |
| Troubleshooting | Required section |
| FAQs | Required (5-8) |

## Tutorial Philosophy

Readers should be able to follow along and complete the task. Every step needs:
- What to do
- How to do it
- What to expect
- What could go wrong

## Article Structure

```markdown
[Opening - What they'll achieve, why it matters]

## Why This Matters / The Problem

[Context for why this tutorial exists]

## What You Need Before Starting

[Prerequisites - tools, access, time]

## Step 1: [Action]

[Instructions with expected outcome]

## Step 2: [Action]

[Continue pattern]

[...]

## Common Issues and Fixes

### Issue: [Problem]
[Solution]

### Issue: [Problem]
[Solution]

## What's Next

[Follow-up actions, related tutorials]

## Frequently Asked Questions

[ACF Accordion - 5-8 FAQs]
```

## Opening Template

State achievement clearly:

> After this guide, you'll have Redis object caching running on your WordPress site. Expect 30-50% faster admin pages and better performance under traffic spikes.

**Include:**
- Specific outcome
- Expected benefit
- Time estimate (optional)

**Never:**
- "In this tutorial, we will..."
- "Today we're going to learn..."
- "Let's dive in..."

## Prerequisites Section

Clear requirements before starting:

```markdown
## What You Need Before Starting

- A VPS with root access (I use Hetzner, works on DigitalOcean too)
- CloudPanel or similar control panel installed
- SSH access configured
- 15-20 minutes of uninterrupted time

**If you're on shared hosting:** Skip this tutorial. Shared hosting doesn't allow Redis installation. Consider upgrading to VPS.
```

**Include:**
- Technical requirements
- Account access needed
- Time estimate
- Who should NOT continue

## Step Structure

Each step needs:

1. **Action verb heading**
2. **Why this step matters** (brief)
3. **Exact instructions**
4. **Expected outcome**
5. **Verification method**

**Example:**
```markdown
## Step 3: Install Redis on Your Server

Redis handles object caching, storing database query results in memory for faster access.

SSH into your server and run:

```bash
sudo apt update
sudo apt install redis-server
```

This takes about 30 seconds. You'll see installation output scrolling by.

**Verify it worked:** Run `redis-cli ping`. You should see `PONG` as the response.
```

## Code Blocks

Always include:
- Language identifier
- Context for what the code does
- Expected output if relevant

```markdown
Run this command to check Redis status:

```bash
sudo systemctl status redis
```

You should see "active (running)" in green.
```

## Screenshots / Images

When suggesting image placement:

```markdown
[IMAGE: Screenshot of CloudPanel Redis settings panel, showing the toggle for enabling Redis]
Alt: CloudPanel Redis configuration interface
```

## Expected Outcomes

After each step, tell readers what they should see:

**Bad:**
> Install the plugin and configure it.

**Good:**
> Install Redis Object Cache from Plugins → Add New. After activation, go to Settings → Redis. You should see "Status: Connected" in green. If you see "Not Connected" in red, Redis isn't running on your server.

## Troubleshooting Section

Anticipate problems:

```markdown
## Common Issues and Fixes

### "Connection refused" error

Redis isn't running. SSH into your server and run:

```bash
sudo systemctl start redis
sudo systemctl enable redis
```

The second command ensures Redis starts automatically after reboots.

### Plugin shows "Not Connected"

Check if Redis is listening on the right socket:

```bash
redis-cli ping
```

If you get `PONG`, Redis is running but the plugin can't find it. Check your wp-config.php for correct Redis host settings.

### No speed improvement

Likely a caching plugin conflict. Disable WP Rocket or FlyingPress temporarily and test again. Object caching and page caching work differently.
```

## Alternative Paths

When there are multiple ways to do something:

```markdown
**Option A: Using command line (recommended)**

```bash
wp plugin install redis-cache --activate
```

**Option B: Using WordPress admin**

Go to Plugins → Add New, search "Redis Object Cache", install and activate.

*I prefer command line for server-related plugins. Fewer clicks, less room for error.*
```

## Time Estimates

Be realistic:

**Bad:** "This takes a few minutes."
**Good:** "Allow 15-20 minutes for first-time setup. 5 minutes if you've done this before."

## Warnings and Notes

Use clear formatting:

```markdown
⚠️ **Warning:** This will clear all existing cache. Make sure you have a backup first.

📝 **Note:** On LiteSpeed servers, use LiteSpeed Cache instead. It has built-in object caching.

✅ **Tip:** Run speed tests before and after to measure improvement.
```

## Closing Section

Point to next steps:

```markdown
## What's Next

Object caching is one piece of the performance puzzle. Now that Redis is handling database queries, look at:

- [Page caching with FlyingPress](link)
- [CDN setup with Bunny CDN](link)
- [Image optimization with ShortPixel](link)

Each layer adds up. A well-optimized WordPress site should load in under 1 second.
```

## FAQ Section

Include:
1. "What if [common problem]?"
2. "Does this work with [popular plugin]?"
3. "Is this free?"
4. "How do I undo this?"
5. "What's the performance impact?"

## Voice in Tutorials

Still conversational, even in technical content:

**Bad:**
> Execute the following command to initiate the installation process.

**Good:**
> Run this to install Redis:

**Bad:**
> It is recommended that users verify the installation.

**Good:**
> Check that it worked by running...

## Tools I Tried and Rejected

Include a section on approaches or tools that DON'T work. This saves readers time and builds trust.

### Structure

```markdown
## What Doesn't Work (Save Your Time)

### [Tool/Method 1]

I spent [time] testing this. The problem: [specific issue]. Don't bother.

### [Tool/Method 2]

Popular recommendation, but [why it fails in practice].
```

---

## ACF Blocks for Tutorials

See `_acf-blocks-for-writing.md` for full syntax.

| Situation | Block |
|-----------|-------|
| Prerequisites list | Checklist block |
| Step-by-step process | Steps block (or manual H2 numbering) |
| Code with syntax highlighting | Code block |
| Warning or important note | Callout block (warning type) |
| Tip or best practice | Callout block (info type) |
| FAQ section | Accordion block |

### Checklist Block Example

```html
<!-- wp:acf/checklist {"name":"acf/checklist","data":{"checklist_title":"Before You Start","checklist_items":{"row-0":{"checklist_item":"WordPress 6.0+"},"row-1":{"checklist_item":"PHP 8.0+"},"row-2":{"checklist_item":"Admin access"}}}} /-->
```

### Callout Block Example

```html
<!-- wp:acf/callout {"name":"acf/callout","data":{"callout_type":"warning","callout_title":"Warning","callout_content":"<p>This will clear your cache. Back up first.</p>"}} /-->
```

---

## Related Patterns

See `_common-patterns.md` for:
- Image placement guidance
- Internal linking requirements (3-5 links)
- Specific numbers pattern

---

## Output Checklist

- [ ] Clear outcome in opening
- [ ] Prerequisites section (consider Checklist block)
- [ ] Numbered steps with action verbs
- [ ] Expected outcome per step
- [ ] Code blocks with language identifiers
- [ ] Image placeholders for complex steps
- [ ] "What Doesn't Work" section
- [ ] Troubleshooting section (3+ issues)
- [ ] 3-5 internal links
- [ ] Next steps/related content
- [ ] FAQs (5-8) in ACF Accordion
- [ ] Verification methods throughout
- [ ] 2000+ words
- [ ] No banned phrases
