---
name: write-concept
description: Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines
---
# Skill: Write JavaScript Concept Documentation
Use this skill when writing or improving concept documentation pages for the 33 JavaScript Concepts project.
## When to Use
- Creating a new concept page in `/docs/concepts/`
- Rewriting or significantly improving an existing concept page
- Reviewing an existing concept page for quality and completeness
- Adding explanatory content to a concept
## Target Audience
Remember: **the reader might be someone who has never coded before or is just learning JavaScript**. Write with empathy for beginners while still providing depth for intermediate developers. Make complex topics feel approachable and never assume prior knowledge without linking to prerequisites.
## Writing Guidelines
### Voice and Tone
- **Conversational but authoritative**: Write like you're explaining to a smart friend
- **Encouraging**: Make complex topics feel approachable
- **Practical**: Focus on real-world applications and use cases
- **Concise**: Respect the reader's time; avoid unnecessary verbosity
- **Question-driven**: Open sections with questions the reader might have
### Avoiding AI-Generated Language
Your writing must sound human, not AI-generated. Here are specific patterns to avoid:
#### Words and Phrases to Avoid
| ❌ Avoid | ✓ Use Instead |
|----------|---------------|
| "Master [concept]" | "Learn [concept]" |
| "dramatically easier/better" | "much easier" or "cleaner" |
| "one fundamental thing" | "one simple thing" |
| "one of the most important concepts" | "This is a big one" |
| "essential points" | "key things to remember" |
| "understanding X deeply improves" | "knowing X well makes Y easier" |
| "To truly understand" | "Let's look at" or "Here's how" |
| "This is crucial" | "This trips people up" |
| "It's worth noting that" | Just state the thing directly |
| "It's important to remember" | "Don't forget:" or "Remember:" |
| "In order to" | "To" |
| "Due to the fact that" | "Because" |
| "At the end of the day" | Remove entirely |
| "When it comes to" | Remove or rephrase |
| "In this section, we will" | Just start explaining |
| "As mentioned earlier" | Remove or link to the section |
#### Repetitive Emphasis Patterns
Don't use the same lead-in pattern repeatedly. Vary your emphasis:
| Instead of repeating... | Vary with... |
|------------------------|--------------|
| "Key insight:" | "Don't forget:", "The pattern:", "Here's the thing:" |
| "Best practice:" | "Pro tip:", "Quick check:", "A good habit:" |
| "Important:" | "Watch out:", "Heads up:", "Note:" |
| "Remember:" | "Keep in mind:", "The rule:", "Think of it this way:" |
#### Em Dash (—) Overuse
AI-generated text overuses em dashes. Limit their use and prefer periods, commas, or colons:
| ❌ Em Dash Overuse | ✓ Better Alternative |
|-------------------|---------------------|
| "async/await — syntactic sugar that..." | "async/await. It's syntactic sugar that..." |
| "understand Promises — async/await is built..." | "understand Promises. async/await is built..." |
| "doesn't throw an error — you just get..." | "doesn't throw an error. You just get..." |
| "outside of async functions — but only in..." | "outside of async functions, but only in..." |
| "Fails fast — if any Promise rejects..." | "Fails fast. If any Promise rejects..." |
| "achieve the same thing — the choice..." | "achieve the same thing. The choice..." |
**When em dashes ARE acceptable:**
- In Key Takeaways section (consistent formatting for the numbered list)
- In MDN card titles (e.g., "async function — MDN")
- In interview answer step-by-step explanations (structured formatting)
- Sparingly when a true parenthetical aside reads naturally
**Rule of thumb:** If you have more than 10-15 em dashes in a 1500-word document outside of structured sections, you're overusing them. After writing, search for "—" and evaluate each one.
#### Superlatives and Filler Words
Avoid vague superlatives that add no information:
| ❌ Avoid | ✓ Use Instead |
|----------|---------------|
| "dramatically" | "much" or remove entirely |
| "fundamentally" | "simply" or be specific about what's fundamental |
| "incredibly" | remove or be specific |
| "extremely" | remove or be specific |
| "absolutely" | remove |
| "basically" | remove (if you need it, you're not explaining clearly) |
| "essentially" | remove or just explain directly |
| "very" | remove or use a stronger word |
| "really" | remove |
| "actually" | remove (unless correcting a misconception) |
| "In fact" | remove (just state the fact) |
| "Interestingly" | remove (let the reader decide if it's interesting) |
#### Stiff/Formal Phrases
Replace formal academic-style phrases with conversational alternatives:
| ❌ Stiff | ✓ Conversational |
|---------|------------------|
| "It should be noted that" | "Note that" or just state it |
| "One might wonder" | "You might wonder" |
| "This enables developers to" | "This lets you" |
| "The aforementioned" | "this" or name it again |
| "Subsequently" | "Then" or "Next" |
| "Utilize" | "Use" |
| "Commence" | "Start" |
| "Prior to" | "Before" |
| "In the event that" | "If" |
| "A considerable amount of" | "A lot of" or "Many" |
#### Playful Touches (Use Sparingly)
Add occasional human touches to make the content feel less robotic, but don't overdo it:
```javascript
// ✓ Good: One playful comment per section
// Callback hell - nested so deep you need a flashlight
// ✓ Good: Conversational aside
// forEach and async don't play well together — it just fires and forgets:
// ✓ Good: Relatable frustration
// Finally, error handling that doesn't make you want to flip a table.
// ❌ Bad: Trying too hard
// Callback hell - it's like a Russian nesting doll had a baby with a spaghetti monster! 🍝
// ❌ Bad: Forced humor
// Let's dive into the AMAZING world of Promises! 🎉🚀
```
**Guidelines:**
- One or two playful touches per major section is enough
- Humor should arise naturally from the content
- Avoid emojis in body text (they're fine in comments occasionally)
- Don't explain your jokes
- If a playful line doesn't work, just be direct instead
### Page Structure (Follow This Exactly)
Every concept page MUST follow this structure in this exact order:
```mdx
---
title: "Concept Name: [Hook] in JavaScript"
sidebarTitle: "Concept Name: [Hook]"
description: "SEO-friendly description in 150-160 characters starting with action word"
---
[Opening hook - Start with engaging questions that make the reader curious]
[Example: "How does JavaScript get data from a server? How do you load user profiles, submit forms, or fetch the latest posts from an API?"]
[Immediately show a simple code example demonstrating the concept]
```javascript
// This is how you [do the thing] in JavaScript
const example = doSomething()
console.log(example) // Expected output
```
[Brief explanation connecting to what they'll learn, with **[inline MDN links](https://developer.mozilla.org/...)** for key terms]
**What you'll learn in this guide:**
- Key learning outcome 1
- Key learning outcome 2
- Key learning outcome 3
- Key learning outcome 4 (aim for 5-7 items)
[Optional: Prerequisites or important notices - place AFTER Info box]
**Prerequisite:** This guide assumes you understand [Related Concept](/concepts/related-concept). If you're not comfortable with that yet, read that guide first!
---
## [First Major Section - e.g., "What is X?"]
[Core explanation with inline MDN links for any new terms/APIs introduced]
[Optional: CardGroup with MDN reference links for this section]
---
## [Analogy Section - e.g., "The Restaurant Analogy"]
[Relatable real-world analogy that makes the concept click]
[ASCII art diagram visualizing the concept]
```
┌─────────────────────────────────────────────────────────────────────────┐
│ DIAGRAM TITLE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ [Visual representation of the concept] │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## [Core Concepts Section]
[Deep dive with code examples, tables, and Mintlify components]
Explanation of the first step
Explanation of the second step
Detailed explanation with code examples
Detailed explanation with code examples
**Quick Rule of Thumb:** [Memorable summary or mnemonic]
---
## [The API/Implementation Section]
[How to actually use the concept in code]
### Basic Usage
```javascript
// Basic example with step-by-step comments
// Step 1: Do this
const step1 = something()
// Step 2: Then this
const step2 = somethingElse(step1)
// Step 3: Finally
console.log(step2) // Expected output
```
### [Advanced Pattern]
```javascript
// More complex real-world example
```
---
## [Common Mistakes Section - e.g., "The #1 Fetch Mistake"]
[Highlight the most common mistake developers make]
```
┌─────────────────────────────────────────────────────────────────────────┐
│ VISUAL COMPARISON │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ WRONG WAY RIGHT WAY │
│ ───────── ───────── │
│ • Problem 1 • Solution 1 │
│ • Problem 2 • Solution 2 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
```javascript
// ❌ WRONG - Explanation of why this is wrong
const bad = wrongApproach()
// ✓ CORRECT - Explanation of the right way
const good = correctApproach()
```
**The Trap:** [Clear explanation of what goes wrong and why]
---
## [Advanced Patterns Section]
[Real-world patterns and best practices]
### Pattern Name
```javascript
// Reusable pattern with practical application
async function realWorldExample() {
// Implementation
}
// Usage
const result = await realWorldExample()
```
---
## Key Takeaways
**The key things to remember:**
1. **First key point** — Brief explanation
2. **Second key point** — Brief explanation
3. **Third key point** — Brief explanation
4. **Fourth key point** — Brief explanation
5. **Fifth key point** — Brief explanation
[Aim for 8-10 key takeaways that summarize everything]
---
## Test Your Knowledge
**Answer:**
[Clear explanation]
```javascript
// Code example demonstrating the answer
```
**Answer:**
[Clear explanation with code if needed]
[Aim for 5-6 questions covering the main topics]
---
## Related Concepts
How it connects to this concept
How it connects to this concept
---
## Reference
Official MDN documentation for the main concept
Additional MDN reference
## Articles
Brief description of what the reader will learn from this article.
[Aim for 4-6 high-quality articles]
## Videos
Brief description of what the video covers.
[Aim for 3-4 quality videos]
```
---
## SEO Guidelines
SEO (Search Engine Optimization) is **critical** for this project. Each concept page should rank for the various ways developers search for that concept. Our goal is to appear in search results for queries like:
- "what is [concept] in JavaScript"
- "how does [concept] work in JavaScript"
- "[concept] JavaScript explained"
- "[concept] JavaScript tutorial"
- "JavaScript [concept] example"
Every writing decision — from title to structure to word choice — should consider search intent.
---
### Target Keywords for Each Concept
Each concept page targets a **keyword cluster** — the family of related search queries. Before writing, identify these for your concept:
| Keyword Type | Pattern | Example (DOM) |
|--------------|---------|---------------|
| **Primary** | [concept] + JavaScript | "DOM JavaScript", "JavaScript DOM" |
| **What is** | what is [concept] in JavaScript | "what is the DOM in JavaScript" |
| **How does** | how does [concept] work | "how does the DOM work in JavaScript" |
| **How to** | how to [action] with [concept] | "how to manipulate the DOM" |
| **Tutorial** | [concept] tutorial/guide/explained | "DOM tutorial JavaScript" |
| **Comparison** | [concept] vs [related] | "DOM vs virtual DOM" |
**More Keyword Cluster Examples:**
| Type | Keywords |
|------|----------|
| Primary | "JavaScript closures", "closures in JavaScript" |
| What is | "what is a closure in JavaScript", "what are closures" |
| How does | "how do closures work in JavaScript", "how closures work" |
| Why use | "why use closures JavaScript", "closure use cases" |
| Example | "JavaScript closure example", "closure examples" |
| Interview | "closure interview questions JavaScript" |
| Type | Keywords |
|------|----------|
| Primary | "JavaScript Promises", "Promises in JavaScript" |
| What is | "what is a Promise in JavaScript", "what are Promises" |
| How does | "how do Promises work", "how Promises work JavaScript" |
| How to | "how to use Promises", "how to chain Promises" |
| Comparison | "Promises vs callbacks", "Promises vs async await" |
| Error | "Promise error handling", "Promise catch" |
| Type | Keywords |
|------|----------|
| Primary | "JavaScript event loop", "event loop JavaScript" |
| What is | "what is the event loop in JavaScript" |
| How does | "how does the event loop work", "how event loop works" |
| Visual | "event loop explained", "event loop visualization" |
| Related | "call stack and event loop", "task queue JavaScript" |
| Type | Keywords |
|------|----------|
| Primary | "JavaScript call stack", "call stack JavaScript" |
| What is | "what is the call stack in JavaScript" |
| How does | "how does the call stack work" |
| Error | "call stack overflow JavaScript", "maximum call stack size exceeded" |
| Visual | "call stack explained", "call stack visualization" |
---
### Title Tag Optimization
The frontmatter has **two title fields**:
- `title` — The page's `` tag (SEO, appears in search results)
- `sidebarTitle` — The sidebar navigation text (cleaner, no "JavaScript" since we're on a JS site)
**The Two-Title Pattern:**
```mdx
---
title: "Closures: How Functions Remember Their Scope in JavaScript"
sidebarTitle: "Closures: How Functions Remember Their Scope"
---
```
- **`title`** ends with "in JavaScript" for SEO keyword placement
- **`sidebarTitle`** omits "JavaScript" for cleaner navigation
**Rules:**
1. **50-60 characters** ideal length for `title` (Google truncates longer titles)
2. **Concept name first** — lead with the topic, "JavaScript" comes at the end
3. **Add a hook** — what will the reader understand or be able to do?
4. **Be specific** — generic titles don't rank
**Title Formulas That Work:**
```
title: "[Concept]: [What You'll Understand] in JavaScript"
sidebarTitle: "[Concept]: [What You'll Understand]"
title: "[Concept]: [Benefit or Outcome] in JavaScript"
sidebarTitle: "[Concept]: [Benefit or Outcome]"
```
**Title Examples:**
| ❌ Bad | ✓ title (SEO) | ✓ sidebarTitle (Navigation) |
|--------|---------------|----------------------------|
| `"Closures"` | `"Closures: How Functions Remember Their Scope in JavaScript"` | `"Closures: How Functions Remember Their Scope"` |
| `"DOM"` | `"DOM: How Browsers Represent Web Pages in JavaScript"` | `"DOM: How Browsers Represent Web Pages"` |
| `"Promises"` | `"Promises: Handling Async Operations in JavaScript"` | `"Promises: Handling Async Operations"` |
| `"Call Stack"` | `"Call Stack: How Function Execution Works in JavaScript"` | `"Call Stack: How Function Execution Works"` |
| `"Event Loop"` | `"Event Loop: How Async Code Actually Runs in JavaScript"` | `"Event Loop: How Async Code Actually Runs"` |
| `"Scope"` | `"Scope and Closures: Variable Visibility in JavaScript"` | `"Scope and Closures: Variable Visibility"` |
| `"this"` | `"this: How Context Binding Works in JavaScript"` | `"this: How Context Binding Works"` |
| `"Prototype"` | `"Prototype Chain: Understanding Inheritance in JavaScript"` | `"Prototype Chain: Understanding Inheritance"` |
**Character Count Check:**
Before finalizing, verify your `title` length:
- Under 50 chars: Consider adding more descriptive context
- 50-60 chars: Perfect length
- Over 60 chars: Will be truncated in search results — shorten it
---
### Meta Description Optimization
The `description` field becomes the meta description — **the snippet users see in search results**. A compelling description increases click-through rate.
**Rules:**
1. **150-160 characters** maximum (Google truncates longer descriptions)
2. **Include primary keyword** in the first half
3. **Include secondary keywords** naturally if space allows
4. **Start with an action word** — "Learn", "Understand", "Discover" (avoid "Master" — sounds AI-generated)
5. **Promise specific value** — what will they learn?
6. **End with a hook** — give them a reason to click
**Description Formula:**
```
[Action word] [what the concept is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3].
```
**Description Examples:**
| Concept | ❌ Too Short (Low CTR) | ✓ SEO-Optimized (150-160 chars) |
|---------|----------------------|--------------------------------|
| DOM | `"Understanding the DOM"` | `"Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering."` |
| Closures | `"Functions that remember"` | `"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."` |
| Promises | `"Async JavaScript"` | `"Understand JavaScript Promises for handling asynchronous operations. Learn to create, chain, and combine Promises, handle errors properly, and write cleaner async code."` |
| Event Loop | `"How async works"` | `"Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking."` |
| Call Stack | `"Function execution"` | `"Learn how the JavaScript call stack tracks function execution. Understand stack frames, execution context, stack overflow errors, and how recursion affects the stack."` |
| this | `"Understanding this"` | `"Learn the 'this' keyword in JavaScript and how context binding works. Covers the four binding rules, arrow function behavior, and how to use call, apply, and bind."` |
**Character Count Check:**
- Under 120 chars: You're leaving value on the table — add more specifics
- 150-160 chars: Optimal length
- Over 160 chars: Will be truncated — edit ruthlessly
---
### Keyword Placement Strategy
Keywords must appear in strategic locations — but **always naturally**. Keyword stuffing hurts rankings.
**Priority Placement Locations:**
| Priority | Location | How to Include |
|----------|----------|----------------|
| 🔴 Critical | Title | Primary keyword in first half |
| 🔴 Critical | Meta description | Primary keyword + 1-2 secondary |
| 🔴 Critical | First paragraph | Natural mention within first 100 words |
| 🟠 High | H2 headings | Question-format headings with keywords |
| 🟠 High | "What you'll learn" box | Topic-related phrases |
| 🟡 Medium | H3 subheadings | Related keywords and concepts |
| 🟡 Medium | Key Takeaways | Reinforce main keywords naturally |
| 🟢 Good | Alt text | If using images, include keywords |
**Example: Keyword Placement for DOM Page**
```mdx
---
title: "DOM: How Browsers Represent Web Pages in JavaScript" ← 🔴 Primary: "in JavaScript" at end
sidebarTitle: "DOM: How Browsers Represent Web Pages" ← Sidebar: no "JavaScript"
description: "Learn how the DOM works in JavaScript. Understand ← 🔴 Primary: "DOM works in JavaScript"
how browsers represent HTML as a tree, select and manipulate ← 🔴 Secondary: "manipulate elements"
elements, traverse nodes, and optimize rendering."
---
How does JavaScript change what you see on a webpage? ← Hook question
The **Document Object Model (DOM)** is a programming interface ← 🔴 Primary keyword in first paragraph
for web documents. It represents your HTML as a **tree of
objects** that JavaScript can read and manipulate.
<Info>
**What you'll learn in this guide:** ← 🟠 Topic reinforcement
- What the DOM actually is
- How to select elements (getElementById vs querySelector) ← Secondary keywords
- How to traverse the DOM tree
- How to create, modify, and remove elements ← "DOM" implicit
- How browsers render the DOM (Critical Rendering Path)
</Info>
## What is the DOM in JavaScript? ← 🟠 H2 with question keyword
The DOM (Document Object Model) is... ← Natural repetition
## How the DOM Works ← 🟠 H2 with "how" keyword
## DOM Manipulation Methods ← 🟡 H3 with related keyword
## Key Takeaways ← 🟡 Reinforce in summary
```
**Warning Signs of Keyword Stuffing:**
- Same exact phrase appears more than 3-4 times per 1000 words
- Sentences read awkwardly because keywords were forced in
- Using keywords where pronouns ("it", "they", "this") would be natural
---
### Answering Search Intent
Google ranks pages that **directly answer the user's query**. Structure your content to satisfy search intent immediately.
**The First Paragraph Rule:**
The first paragraph after any H2 should directly answer the implied question. Don't build up to the answer — lead with it.
```mdx
<!-- ❌ BAD: Builds up to the answer -->
## What is the Event Loop?
Before we can understand the event loop, we need to talk about JavaScript's
single-threaded nature. You see, JavaScript can only do one thing at a time,
and this creates some interesting challenges. The way JavaScript handles
this is through something called... the event loop.
<!-- ✓ GOOD: Answers immediately -->
## What is the Event Loop?
The **event loop** is JavaScript's mechanism for executing code, handling events,
and managing asynchronous operations. It continuously monitors the call stack
and task queue, moving queued callbacks to the stack when it's empty — this is
how JavaScript handles async code despite being single-threaded.
```
**Question-Format H2 Headings:**
Use H2s that match how people search:
| Search Query | H2 to Use |
|--------------|-----------|
| "what is the DOM" | `## What is the DOM?` |
| "how closures work" | `## How Do Closures Work?` |
| "why use promises" | `## Why Use Promises?` |
| "when to use async await" | `## When Should You Use async/await?` |
---
### Featured Snippet Optimization
Featured snippets appear at **position zero** — above all organic results. Structure your content to win them.
**Snippet Types and How to Win Them:**
```
┌─────────────────────────────────────────────────────────────────────────┐
│ FEATURED SNIPPET TYPES │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ QUERY TYPE SNIPPET FORMAT YOUR CONTENT STRUCTURE │
│ ─────────── ────────────── ───────────────────────── │
│ │
│ "What is X" Paragraph 40-60 word definition │
│ immediately after H2 │
│ │
│ "How to X" Numbered list <Steps> component or │
│ numbered Markdown list │
│ │
│ "X vs Y" Table Comparison table with │
│ clear column headers │
│ │
│ "Types of X" Bulleted list Bullet list under │
│ descriptive H2 │
│ │
│ "[X] examples" Bulleted list or Code examples with │
│ code block brief explanations │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
**Pattern 1: Definition Snippet (40-60 words)**
For "what is [concept]" queries:
```mdx
## What is a Closure in JavaScript?
A **closure** is a function that retains access to variables from its outer
(enclosing) scope, even after that outer function has finished executing.
Closures are created every time a function is created in JavaScript, allowing
inner functions to "remember" and access their lexical environment.
```
**Why this wins:**
- H2 matches search query exactly
- Bold keyword in first sentence
- 40-60 word complete definition
- Explains the "why" not just the "what"
**Pattern 2: List Snippet (Steps)**
For "how to [action]" queries:
```mdx
## How to Make a Fetch Request in JavaScript
<Steps>
<Step title="1. Call fetch() with the URL">
The `fetch()` function takes a URL and returns a Promise that resolves to a Response object.
</Step>
<Step title="2. Check if the response was successful">
Always verify `response.ok` before processing — fetch doesn't throw on HTTP errors.
</Step>
<Step title="3. Parse the response body">
Use `response.json()` for JSON data, `response.text()` for plain text.
</Step>
<Step title="4. Handle errors properly">
Wrap everything in try/catch to handle both network and HTTP errors.
</Step>
</Steps>
```
**Pattern 3: Table Snippet (Comparison)**
For "[X] vs [Y]" queries:
```mdx
## == vs === in JavaScript
| Aspect | `==` (Loose Equality) | `===` (Strict Equality) |
|--------|----------------------|------------------------|
| Type coercion | Yes — converts types before comparing | No — types must match |
| Speed | Slower (coercion overhead) | Faster (no coercion) |
| Predictability | Can produce surprising results | Always predictable |
| Recommendation | Avoid in most cases | Use by default |
```javascript
// Examples
5 == "5" // true (string coerced to number)
5 === "5" // false (different types)
```
```
**Pattern 4: List Snippet (Types/Categories)**
For "types of [concept]" queries:
```mdx
## Types of Scope in JavaScript
JavaScript has three types of scope that determine where variables are accessible:
- **Global Scope** — Variables declared outside any function or block; accessible everywhere
- **Function Scope** — Variables declared inside a function with `var`; accessible only within that function
- **Block Scope** — Variables declared with `let` or `const` inside `{}`; accessible only within that block
```
---
### Content Structure for SEO
How you structure content affects both rankings and user experience.
**The Inverted Pyramid:**
Put the most important information first. Search engines and users both prefer content that answers questions immediately.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ THE INVERTED PYRAMID │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ ANSWER THE QUESTION │ ← First 100 words │
│ │ Definition + Core Concept │ (most important) │
│ └──────────────────┬──────────────────┘ │
│ │ │
│ ┌────────────────┴────────────────┐ │
│ │ EXPLAIN HOW IT WORKS │ ← Next 300 words │
│ │ Mechanism + Visual Diagram │ (supporting info) │
│ └────────────────┬─────────────────┘ │
│ │ │
│ ┌──────────────────┴──────────────────┐ │
│ │ SHOW PRACTICAL EXAMPLES │ ← Code examples │
│ │ Code + Step-by-step │ (proof it works) │
│ └──────────────────┬──────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ COVER EDGE CASES │ ← Advanced │
│ │ Common mistakes, gotchas │ (depth) │
│ └──────────────────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────────────────┴──────────────────────────┐ │
│ │ ADDITIONAL RESOURCES │ ← External │
│ │ Related concepts, articles, videos │ (links) │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
**Scannable Content Patterns:**
Google favors content that's easy to scan. Use these elements:
| Element | SEO Benefit | When to Use |
|---------|-------------|-------------|
| Short paragraphs | Reduces bounce rate | Always (2-4 sentences max) |
| Bullet lists | Often become featured snippets | Lists of 3+ items |
| Numbered lists | "How to" snippet potential | Sequential steps |
| Tables | High snippet potential | Comparisons, reference data |
| Bold text | Highlights keywords for crawlers | First mention of key terms |
| Headings (H2/H3) | Structure signals to Google | Every major topic shift |
**Content Length Guidelines:**
| Length | Assessment | Action |
|--------|------------|--------|
| Under 1,000 words | Too thin | Add more depth, examples, edge cases |
| 1,000-1,500 words | Minimum viable | Acceptable for simple concepts |
| 1,500-2,500 words | Good | Standard for most concept pages |
| 2,500-4,000 words | Excellent | Ideal for comprehensive guides |
| Over 4,000 words | Evaluate | Consider splitting into multiple pages |
**Note:** Length alone doesn't guarantee rankings. Every section must add value — don't pad content.
---
### Internal Linking for SEO
Internal links help search engines understand your site structure and distribute page authority.
**Topic Cluster Strategy:**
Think of concept pages as an interconnected network. Every concept should link to 3-5 related concepts:
```
┌─────────────────┐
┌───────│ Promises │───────┐
│ └────────┬────────┘ │
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────────┐ ┌─────────────┐
│async/await│◄──►│ Event Loop │◄──►│ Callbacks │
└───────────┘ └───────────────┘ └─────────────┘
│ │ │
│ ▼ │
│ ┌───────────────┐ │
└──────►│ Call Stack │◄───────┘
└───────────────┘
```
**Link Placement Guidelines:**
1. **In Prerequisites (Warning box):**
```mdx
<Warning>
**Prerequisite:** This guide assumes you understand [Promises](/concepts/promises) and the [Event Loop](/concepts/event-loop). Read those first if you're not comfortable with asynchronous JavaScript.
</Warning>
```
2. **In Body Content (natural context):**
```mdx
When the callback finishes, it's added to the task queue — which is managed by the [event loop](/concepts/event-loop).
```
3. **In Related Concepts Section:**
```mdx
<CardGroup cols={2}>
<Card title="Promises" icon="handshake" href="/concepts/promises">
async/await is built on top of Promises
</Card>
<Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop">
How JavaScript manages async operations
</Card>
</CardGroup>
```
**Anchor Text Best Practices:**
| ❌ Bad Anchor Text | ✓ Good Anchor Text | Why |
|-------------------|-------------------|-----|
| "click here" | "event loop guide" | Descriptive, includes keyword |
| "this article" | "our Promises concept" | Tells Google what page is about |
| "here" | "JavaScript closures" | Keywords in anchor text |
| "read more" | "understanding the call stack" | Natural, informative |
---
### URL and Slug Best Practices
URLs (slugs) are a minor but meaningful ranking factor.
**Rules:**
1. **Use lowercase** — `closures` not `Closures`
2. **Use hyphens** — `call-stack` not `call_stack` or `callstack`
3. **Keep it short** — aim for 3-5 words maximum
4. **Include primary keyword** — the concept name
5. **Avoid stop words** — skip "the", "and", "in", "of" unless necessary
**Slug Examples:**
| Concept | ❌ Avoid | ✓ Use |
|---------|---------|-------|
| The Event Loop | `the-event-loop` | `event-loop` |
| this, call, apply and bind | `this-call-apply-and-bind` | `this-call-apply-bind` |
| Scope and Closures | `scope-and-closures` | `scope-and-closures` (acceptable) or `scope-closures` |
| DOM and Layout Trees | `dom-and-layout-trees` | `dom` or `dom-layout-trees` |
**Note:** For this project, slugs are already set. When creating new pages, follow these conventions.
---
### Opening Paragraph: The SEO Power Move
The opening paragraph is prime SEO real estate. It should:
1. Hook the reader with a question they're asking
2. Include the primary keyword naturally
3. Provide a brief definition or answer
4. Set up what they'll learn
**Template:**
```mdx
[Question hook that matches search intent?] [Maybe another question?]
The **[Primary Keyword]** is [brief definition that answers "what is X"].
[One sentence explaining why it matters or what it enables].
```javascript
// Immediately show a simple example
```
[Brief transition to "What you'll learn" box]
```
**Example (Closures):**
```mdx
Why do some functions seem to "remember" variables that should have disappeared?
How can a callback still access variables from a function that finished running
long ago?
The answer is **closures** — one of JavaScript's most powerful (and often
misunderstood) features. A closure is a function that retains access to its
outer scope's variables, even after that outer scope has finished executing.
```javascript
function createCounter() {
let count = 0 // This variable is "enclosed" by the returned function
return function() {
count++
return count
}
}
const counter = createCounter()
console.log(counter()) // 1
console.log(counter()) // 2 — it remembers!
```
Understanding closures unlocks patterns like private variables, factory functions,
and the module pattern that power modern JavaScript.
```
**Why this works for SEO:**
- Question hooks match how people search ("why do functions remember")
- Bold keyword in first paragraph
- Direct definition answers "what is a closure"
- Code example demonstrates immediately
- Natural setup for learning objectives
---
## Inline Linking Rules (Critical!)
### Always Link to MDN
Whenever you introduce a new Web API, method, object, or JavaScript concept, **link to MDN immediately**. This gives readers a path to deeper learning.
```mdx
<!-- ✓ CORRECT: Link on first mention -->
The **[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)** is JavaScript's modern way to make network requests.
The **[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)** object contains everything about the server's reply.
Most modern APIs return data in **[JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** format.
<!-- ❌ WRONG: No links -->
The Fetch API is JavaScript's modern way to make network requests.
```
### Link to Related Concept Pages
When mentioning concepts covered in other pages, link to them:
```mdx
<!-- ✓ CORRECT: Internal links to related concepts -->
If you're not familiar with it, check out our [async/await concept](/concepts/async-await) first.
This guide assumes you understand [Promises](/concepts/promises).
<!-- ❌ WRONG: No internal links -->
If you're not familiar with async/await, you should learn that first.
```
### Common MDN Link Patterns
| Concept | MDN URL Pattern |
|---------|-----------------|
| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` |
| JavaScript Objects | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` |
| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` |
| HTTP Methods | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/{METHOD}` |
| HTTP Headers | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers` |
---
## Code Examples Best Practices
### 1. Start with the Simplest Possible Example
```javascript
// ✓ GOOD: Start with the absolute basics
// This is how you fetch data in JavaScript
const response = await fetch('https://api.example.com/users/1')
const user = await response.json()
console.log(user.name) // "Alice"
```
### 2. Use Step-by-Step Comments
```javascript
// Step 1: fetch() returns a Promise that resolves to a Response object
const responsePromise = fetch('https://api.example.com/users')
// Step 2: When the response arrives, we get a Response object
responsePromise.then(response => {
console.log(response.status) // 200
// Step 3: The body is a stream, we need to parse it
return response.json()
})
.then(data => {
// Step 4: Now we have the actual data
console.log(data)
})
```
### 3. Show Output in Comments
```javascript
const greeting = "Hello"
console.log(typeof greeting) // "string"
const numbers = [1, 2, 3]
console.log(numbers.length) // 3
```
### 4. Use ❌ and ✓ for Wrong/Correct Patterns
```javascript
// ❌ WRONG - This misses HTTP errors!
try {
const response = await fetch('/api/users/999')
const data = await response.json()
} catch (error) {
// Only catches NETWORK errors, not 404s!
}
// ✓ CORRECT - Check response.ok
try {
const response = await fetch('/api/users/999')
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`)
}
const data = await response.json()
} catch (error) {
// Now catches both network AND HTTP errors
}
```
### 5. Use Meaningful Variable Names
```javascript
// ❌ BAD
const x = [1, 2, 3]
const y = x.map(z => z * 2)
// ✓ GOOD
const numbers = [1, 2, 3]
const doubled = numbers.map(num => num * 2)
```
### 6. Progress from Simple to Complex
```javascript
// Level 1: Basic usage
fetch('/api/users')
// Level 2: With options
fetch('/api/users', {
method: 'POST',
body: JSON.stringify({ name: 'Alice' })
})
// Level 3: Full real-world pattern
async function createUser(userData) {
const response = await fetch('/api/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(userData)
})
if (!response.ok) {
throw new Error(`Failed to create user: ${response.status}`)
}
return response.json()
}
```
---
## Resource Curation Guidelines
External resources (articles, videos) are valuable, but must meet quality standards.
### Quality Standards
Only include resources that are:
1. **JavaScript-focused** — No resources primarily about other languages (C#, Python, Java, etc.), even if the concepts are similar
2. **Still accessible** — Verify all links work before publishing
3. **High quality** — From reputable sources (MDN, javascript.info, freeCodeCamp, well-known educators)
4. **Up to date** — Avoid outdated resources; check publication dates for time-sensitive topics
5. **Accurate** — Skim the content to verify it doesn't teach anti-patterns
### Writing Resource Descriptions
Each resource needs a **specific, engaging 2-sentence description** explaining what makes it unique. Generic descriptions waste the reader's time.
```mdx
<!-- ❌ Generic (bad) -->
<Card title="JavaScript Promises Tutorial" icon="newspaper" href="...">
Learn about Promises in JavaScript.
</Card>
<!-- ❌ Generic (bad) -->
<Card title="Async/Await Explained" icon="newspaper" href="...">
A comprehensive guide to async/await.
</Card>
<!-- ✓ Specific (good) -->
<Card title="JavaScript Async/Await Tutorial" icon="newspaper" href="https://javascript.info/async-await">
The go-to reference for async/await fundamentals. Includes exercises at the end to test your understanding of rewriting promise chains.
</Card>
<!-- ✓ Specific (good) -->
<Card title="JavaScript Visualized: Promises & Async/Await" icon="newspaper" href="...">
Animated GIFs showing the call stack, microtask queue, and event loop in action. This is how async/await finally "clicked" for thousands of developers.
</Card>
<!-- ✓ Specific (good) -->
<Card title="How to Escape Async/Await Hell" icon="newspaper" href="...">
The pizza-and-drinks ordering example makes parallel vs sequential execution crystal clear. Essential reading once you know the basics.
</Card>
```
**Description Formula:**
1. **Sentence 1:** What makes this resource unique OR what it specifically covers
2. **Sentence 2:** Why a reader should click (what they'll gain, who it's best for, what stands out)
**Avoid in descriptions:**
- "Comprehensive guide to..." (vague)
- "Great tutorial on..." (vague)
- "Learn all about..." (vague)
- "Everything you need to know about..." (cliché)
### Recommended Sources
**Articles (Prioritize):**
| Source | Why |
|--------|-----|
| javascript.info | Comprehensive, well-maintained, exercises included |
| MDN Web Docs | Official reference, always accurate |
| freeCodeCamp | Beginner-friendly, practical tutorials |
| dev.to (Lydia Hallie, etc.) | Visual explanations, community favorites |
| CSS-Tricks | DOM, browser APIs, visual topics |
**Videos (Prioritize):**
| Creator | Style |
|---------|-------|
| Web Dev Simplified | Clear, beginner-friendly, concise |
| Fireship | Fast-paced, modern, entertaining |
| Traversy Media | Comprehensive crash courses |
| Fun Fun Function | Deep-dives with personality |
| Wes Bos | Practical, real-world focused |
**Avoid:**
- Resources in other programming languages (C#, Python, Java) even if concepts overlap
- Outdated tutorials (pre-ES6 syntax for modern concepts)
- Paywalled content (unless there's a free tier)
- Low-quality Medium articles (check engagement and accuracy)
- Resources that teach anti-patterns
- Videos over 2 hours (link to specific timestamps if valuable)
### Verifying Resources
Before including any resource:
1. **Click the link** — Verify it loads and isn't behind a paywall
2. **Skim the content** — Ensure it's accurate and well-written
3. **Check the date** — For time-sensitive topics, prefer recent content
4. **Read comments/reactions** — Community feedback reveals quality issues
5. **Test code examples** — If they include code, verify it works
---
## ASCII Art Diagrams
Use ASCII art to visualize concepts. Make them boxed and labeled:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ THE REQUEST-RESPONSE CYCLE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ YOU (Browser) KITCHEN (Server) │
│ ┌──────────┐ ┌──────────────┐ │
│ │ │ ──── "I'd like pasta" ────► │ │ │
│ │ :) │ (REQUEST) │ [chef] │ │
│ │ │ │ │ │
│ │ │ ◄──── Here you go! ──────── │ │ │
│ │ │ (RESPONSE) │ │ │
│ └──────────┘ └──────────────┘ │
│ │
│ The waiter (HTTP) is the protocol that makes this exchange work! │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## Mintlify Components Reference
| Component | When to Use |
|-----------|-------------|
| `<Info>` | "What you'll learn" boxes, Key Takeaways |
| `<Warning>` | Common mistakes, gotchas, prerequisites |
| `<Tip>` | Pro tips, rules of thumb, best practices |
| `<Note>` | Additional context, side notes |
| `<AccordionGroup>` | Expandable content, Q&A sections, optional deep-dives |
| `<Tabs>` | Comparing different approaches side-by-side |
| `<Steps>` | Sequential processes, numbered workflows |
| `<CardGroup>` | Resource links (articles, videos, references) |
| `<Card>` | Individual resource with icon and link |
### Card Icons Reference
| Content Type | Icon |
|--------------|------|
| MDN/Official Docs | `book` |
| Articles/Blog Posts | `newspaper` |
| Videos | `video` |
| Courses | `graduation-cap` |
| Related Concepts | Context-appropriate (`handshake`, `hourglass`, `arrows-spin`, `sitemap`, etc.) |
---
## Quality Checklist
Before finalizing a concept page, verify ALL of these:
### Structure
- [ ] Opens with engaging questions that hook the reader
- [ ] Shows a simple code example immediately after the opening
- [ ] Has "What you'll learn" Info box right after the opening
- [ ] Major sections are separated by `---` horizontal rules
- [ ] Has a real-world analogy with ASCII art diagram
- [ ] Has a "Common Mistakes" or "The #1 Mistake" section
- [ ] Has a "Key Takeaways" section summarizing 8-10 points
- [ ] Has a "Test Your Knowledge" section with 5-6 Q&As
- [ ] Ends with Related Concepts, Reference, Articles, Videos in that order
### Linking
- [ ] All new Web APIs/methods have inline MDN links on first mention
- [ ] All related concepts link to their concept pages (`/concepts/slug`)
- [ ] Reference section has multiple MDN links
- [ ] 4-6 quality articles with descriptions
- [ ] 3-4 quality videos with descriptions
### Code Examples
- [ ] First code example is dead simple
- [ ] Uses step-by-step comments for complex examples
- [ ] Shows output in comments (`// "result"`)
- [ ] Uses ❌ and ✓ for wrong/correct patterns
- [ ] Uses meaningful variable names
- [ ] Progresses from simple to complex
### Content Quality
- [ ] Written for someone who might be new to coding
- [ ] Prerequisites are noted with Warning component
- [ ] No assumptions about prior knowledge without links
- [ ] Tables used for quick reference information
- [ ] ASCII diagrams for visual concepts
### Language Quality
- [ ] Description starts with "Learn" or "Understand" (not "Master")
- [ ] No overuse of em dashes (fewer than 15 outside Key Takeaways and structured sections)
- [ ] No AI superlatives: "dramatically", "fundamentally", "incredibly", "extremely"
- [ ] No stiff phrases: "one of the most important", "essential points", "It should be noted"
- [ ] Emphasis patterns vary (not all "Key insight:" or "Best practice:")
- [ ] Playful touches are sparse (1-2 per major section maximum)
- [ ] No filler words: "basically", "essentially", "actually", "very", "really"
- [ ] Sentences are direct (no "In order to", "Due to the fact that")
### Resource Quality
- [ ] All article/video links are verified working
- [ ] All resources are JavaScript-focused (no C#, Python, Java resources)
- [ ] Each resource has a specific 2-sentence description (not generic)
- [ ] Resource descriptions explain what makes each unique
- [ ] No outdated resources (check dates for time-sensitive topics)
- [ ] 4-6 articles from reputable sources
- [ ] 3-4 videos from quality creators
---
## Writing Tests
When adding code examples, create corresponding tests in `/tests/`:
```javascript
// tests/{category}/{concept-name}/{concept-name}.test.js
import { describe, it, expect } from 'vitest'
describe('Concept Name', () => {
describe('Basic Examples', () => {
it('should demonstrate the core concept', () => {
// Convert console.log examples to expect assertions
expect(typeof "hello").toBe("string")
})
})
describe('Common Mistakes', () => {
it('should show the wrong behavior', () => {
// Test the "wrong" example to prove it's actually wrong
})
it('should show the correct behavior', () => {
// Test the "correct" example
})
})
})
```
---
## SEO Checklist
Verify these elements before publishing any concept page:
### Title & Meta Description
- [ ] **Title is 50-60 characters** — check with character counter
- [ ] **Title ends with "in JavaScript"** — SEO keyword at end
- [ ] **Title has a compelling hook** — tells reader what they'll understand
- [ ] **sidebarTitle matches title but without "in JavaScript"** — cleaner navigation
- [ ] **Description is 150-160 characters** — don't leave value on the table
- [ ] **Description includes primary keyword** in first sentence
- [ ] **Description includes 1-2 secondary keywords** naturally
- [ ] **Description starts with action word** (Learn, Understand, Discover — avoid "Master")
- [ ] **Description promises specific value** — what will they learn?
### Keyword Placement
- [ ] **Primary keyword in title**
- [ ] **Primary keyword in description**
- [ ] **Primary keyword in first paragraph** (within first 100 words)
- [ ] **Primary keyword in at least one H2 heading**
- [ ] **Secondary keywords in H2/H3 headings** where natural
- [ ] **Keywords in "What you'll learn" box items**
- [ ] **No keyword stuffing** — content reads naturally
### Content Structure
- [ ] **Opens with question hook** matching search intent
- [ ] **Shows code example in first 200 words**
- [ ] **First paragraph after H2s directly answers** the implied question
- [ ] **Content is 1,500+ words** (comprehensive coverage)
- [ ] **Short paragraphs** (2-4 sentences maximum)
- [ ] **Uses bullet lists** for 3+ related items
- [ ] **Uses numbered lists** for sequential processes
- [ ] **Uses tables** for comparisons and reference data
- [ ] **Key terms bolded** on first mention with MDN links
### Featured Snippet Optimization
- [ ] **"What is X" section has 40-60 word definition paragraph**
- [ ] **"How to" sections use numbered steps or `<Steps>` component**
- [ ] **Comparison sections use tables** with clear headers
- [ ] **At least one H2 is phrased as a question** matching search query
### Internal Linking
- [ ] **Links to 3-5 related concept pages** in body content
- [ ] **Uses descriptive anchor text** (not "click here" or "here")
- [ ] **Prerequisites linked in Warning component** at start
- [ ] **Related Concepts section has 4 cards** with relevant concepts
- [ ] **Links appear in natural context** — not forced
### Technical SEO
- [ ] **Slug is lowercase with hyphens**
- [ ] **Slug contains primary keyword**
- [ ] **Slug is 3-5 words maximum**
- [ ] **All external links use proper URLs** (no broken links)
- [ ] **MDN links are current** (check they resolve)