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:
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:
---
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]
[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]
[The API/Implementation Section]
[How to actually use the concept in code]
Basic Usage
const step1 = something()
const step2 = somethingElse(step1)
console.log(step2)
[Advanced Pattern]
[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 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
const bad = wrongApproach()
const good = correctApproach()
[Advanced Patterns Section]
[Real-world patterns and best practices]
Pattern Name
async function realWorldExample() {
}
const result = await realWorldExample()
Key Takeaways
-
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]
Test Your Knowledge
[Clear explanation]
```javascript
// Code example demonstrating the answer
```
[Clear explanation with code if needed]
[Aim for 5-6 questions covering the main topics]
Related Concepts
Reference
Articles
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:
Title Tag Optimization
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 navigation
Rules:
- 50-60 characters ideal length for
title (Google truncates longer titles)
- Concept name first — lead with the topic, "JavaScript" comes at the end
- Add a hook — what will the reader understand or be able to do?
- 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:
- 150-160 characters maximum (Google truncates longer descriptions)
- Include primary keyword in the first half
- Include secondary keywords naturally if space allows
- Start with an action word — "Learn", "Understand", "Discover" (avoid "Master" — sounds AI-generated)
- Promise specific value — what will they learn?
- End with a hook — give them a reason to click
Description Formula:
[Action word] [what the concept is] in JavaScri
