write-concept

# 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] <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> --- ## [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] <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> --- ## [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() ``` <Warning> **The Trap:** [Clear explanation of what goes wrong and why] </Warning> --- ## [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 <Info> **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] </Info> --- ## Test Your Knowledge <AccordionGroup> <Accordion title="Question 1: [Specific question about the concept]"> **Answer:** [Clear explanation] ```javascript // Code example demonstrating the answer ``` </Accordion> <Accordion title="Question 2: [Another question]"> **Answer:** [Clear explanation with code if needed] </Accordion> [Aim for 5-6 questions covering the main topics] </AccordionGroup> --- ## Related Concepts <CardGroup cols={2}> <Card title="Related Concept 1" icon="icon-name" href="/concepts/slug"> How it connects to this concept </Card> <Card title="Related Concept 2" icon="icon-name" href="/concepts/slug"> How it connects to this concept </Card> </CardGroup> --- ## Reference <CardGroup cols={2}> <Card title="Main Topic — MDN" icon="book" href="https://developer.mozilla.org/..."> Official MDN documentation for the main concept </Card> <Card title="Related API — MDN" icon="book" href="https://developer.mozilla.org/..."> Additional MDN reference </Card> </CardGroup> ## Articles <CardGroup cols={2}> <Card title="Article Title" icon="newspaper" href="https://..."> Brief description of what the reader will learn from this article. </Card> [Aim for 4-6 high-quality articles] </CardGroup> ## Videos <CardGroup cols={2}> <Card title="Video Title" icon="video" href="https://..."> Brief description of what the video covers. </Card> [Aim for 3-4 quality videos] </CardGroup> ``` --- ## 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) |