Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines
Use this skill when writing or improving concept documentation pages for the 33 JavaScript Concepts project.
/docs/concepts/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.
Your writing must sound human, not AI-generated. Here are specific patterns 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 |
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:" |
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:
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.
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) |
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" |
Add occasional human touches to make the content feel less robotic, but don't overdo it:
// ✓ 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:
Every concept page MUST follow this structure in this exact order:
---
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 for key terms]
<Info> **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) </Info> <Warning> [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! </Warning>[Core explanation with inline MDN links for any new terms/APIs introduced]
[Optional: CardGroup with MDN reference links for this section]
[Relatable real-world analogy that makes the concept click]
[ASCII art diagram visualizing the concept]
┌─────────────────────────────────────────────────────────────────────────┐
│ DIAGRAM TITLE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ [Visual representation of the concept] │
│ │
└─────────────────────────────────────────────────────────────────────────┘
[Deep dive with code examples, tables, and Mintlify components]
<Steps> <Step title="Step 1"> Explanation of the first step </Step> <Step title="Step 2"> Explanation of the second step </Step> </Steps> <AccordionGroup> <Accordion title="Subtopic 1"> Detailed explanation with code examples </Accordion> <Accordion title="Subtopic 2"> Detailed explanation with code examples </Accordion> </AccordionGroup> <Tip> **Quick Rule of Thumb:** [Memorable summary or mnemonic] </Tip>[How to actually use the concept in code]
// 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
// More complex real-world example
[Highlight the most common mistake developers make]
┌─────────────────────────────────────────────────────────────────────────┐
│ VISUAL COMPARISON │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ WRONG WAY RIGHT WAY │
│ ───────── ───────── │
│ • Problem 1 • Solution 1 │
│ • Problem 2 • Solution 2 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
// ❌ WRONG - Explanation of why this is wrong
const bad = wrongApproach()
// ✓ CORRECT - Explanation of the right way
const good = correctApproach()
[Real-world patterns and best practices]
// Reusable pattern with practical application
async function realWorldExample() {
// Implementation
}
// Usage
const result = await realWorldExample()
First key point — Brief explanation
Second key point — Brief explanation
Third key point — Brief explanation
Fourth key point — Brief explanation
Fifth key point — Brief explanation
[Aim for 8-10 key takeaways that summarize everything] </Info>
[Clear explanation]
```javascript
// Code example demonstrating the answer
```
[Clear explanation with code if needed]
[Aim for 5-6 questions covering the main topics] </AccordionGroup>
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:
Every writing decision — from title to structure to word choice — should consider search intent.
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:
<AccordionGroup> <Accordion title="Closures Keyword Cluster"> | 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" | </Accordion> <Accordion title="Promises Keyword Cluster"> | 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" | </Accordion> <Accordion title="Event Loop Keyword Cluster"> | 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" | </Accordion> <Accordion title="Call Stack Keyword Cluster"> | 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" | </Accordion> </AccordionGroup>The frontmatter has two title fields:
title — The page's <title> 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:
---
title: "Closures: How Functions Remember Their Scope in JavaScript"
sidebarTitle: "Closures: How Functions Remember Their Scope"
---
title ends with "in JavaScript" for SEO keyword placementsidebarTitle omits "JavaScript" for cleaner navigationRules:
title (Google truncates longer titles)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:
The description field becomes the meta description — the snippet users see in search results. A compelling description increases click-through rate.
Rules:
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:
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
---
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:
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.
<!-- ❌ 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 onl
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer