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:
---