docs-writer-learn

Learn Page Writer

Persona

Voice: Patient teacher guiding a friend through concepts Tone: Conversational, warm, encouraging

Voice & Style

For tone, capitalization, jargon, and prose patterns, invoke /docs-voice .

Page Structure Variants

Standard Learn Page (Most Common)

title: Page Title

<Intro> 1-3 sentences introducing the concept. Use italics for new terms. </Intro>

Learning outcome 1
Learning outcome 2
Learning outcome 3-5

</YouWillLearn>

Section Name {/section-id/}

Content with Sandpack examples, Pitfalls, Notes, DeepDives...

Another Section {/another-section/}

Challenge title {/challenge-id/}

Description...

<Hint> Optional guidance (single paragraph) </Hint>

<Sandpack> {/* Starting code */} </Sandpack>

<Solution> Explanation...

<Sandpack> {/* Fixed code */} </Sandpack> </Solution>

</Challenges>

Chapter Introduction Page

For pages that introduce a chapter (like describing-the-ui.md, managing-state.md):

Sub-page title to learn...
Another page to learn...

</YouWillLearn>

Preview Section {/section-id/}

Preview description with mini Sandpack example

Read Page Title to learn how to...

</LearnMore>

What's next? {/whats-next/}

Head over to First Page to start reading this chapter page by page!

Important: Chapter intro pages do NOT include <Recap> or <Challenges> sections.

Tutorial Page

For step-by-step tutorials (like tutorial-tic-tac-toe.md):

<Intro> Brief statement of what will be built </Intro>

<Note> Alternative learning path offered </Note>

Table of contents (prose listing of major sections)

Setup {/setup/}

...

Main Content {/main-content/}

Progressive code building with ### subsections

No YouWillLearn, Recap, or Challenges

Ends with ordered list of "extra credit" improvements

Reference-Style Learn Page

For pages with heavy API documentation (like typescript.md):

Link to section
Link to another section

</YouWillLearn>

Sections with ### subsections

Further learning {/further-learning/}

No Recap or Challenges

Heading ID Conventions

All headings require IDs in {/kebab-case/} format:

Section Title {/section-title/}

Subsection Title {/subsection-title/}

DeepDive Title {/deepdive-title/}

ID Generation Rules:

Lowercase everything
Replace spaces with hyphens
Remove apostrophes, quotes
Remove or convert special chars (: , ? , ! , . , parentheses)

Examples:

"What's React?" → {/whats-react/}
"Step 1: Create the context" → {/step-1-create-the-context/}
"Conditional (ternary) operator (? :)" → {/conditional-ternary-operator--/}

Teaching Patterns

Problem-First Teaching

Show broken/problematic code BEFORE the solution:

Present problematic approach with // 🔴 Avoid: comment
Explain WHY it's wrong (don't just say it is)
Show the solution with // ✅ Good: comment
Invite experimentation

Progressive Complexity

Build understanding in layers:

Show simplest working version
Identify limitation or repetition
Introduce solution incrementally
Show complete solution
Invite experimentation: "Try changing..."

Numbered Step Patterns

For multi-step processes:

As section headings:

Step 1: Action to take {/step-1-action/}

Step 2: Next action {/step-2-next-action/}

As inline lists:

To implement this:

Declare inputRef with the useRef Hook.
Pass it as <input ref={inputRef}>.
Read the input DOM node from inputRef.current.

Interactive Invitations

After Sandpack examples, encourage experimentation:

"Try changing X to Y. See how...?"
"Try it in the sandbox above!"
"Click each button separately:"
"Have a guess!"
"Verify that..."

Decision Questions

Help readers build intuition:

"When you're not sure whether some code should be in an Effect or in an event handler, ask yourself why this code needs to run."

Component Placement Order

<Intro>
First after frontmatter
<YouWillLearn>
After Intro (standard/chapter pages)
Body content with <Note> , <Pitfall> , <DeepDive> placed contextually
<Recap>
Before Challenges (standard pages only)
<Challenges>
End of page (standard pages only)

For component structure and syntax, invoke /docs-components .

Code Examples

For Sandpack file structure, naming conventions, code style, and pedagogical markers, invoke /docs-sandpack .

Cross-Referencing

When to Link

Link to /learn:

Explaining concepts or mental models
Teaching how things work together
Tutorials and guides
"Why" questions

Link to /reference:

API details, Hook signatures
Parameter lists and return values
Rules and restrictions
"What exactly" questions

Link Formats

concept name useState section link MDN

Section Dividers

Important: Learn pages typically do NOT use --- dividers. The heading hierarchy provides sufficient structure. Only consider dividers in exceptional cases like separating main content from meta/contribution sections.

Do's and Don'ts

Do:

Use "you" to address the reader
Show broken code before fixes
Explain behavior before naming concepts
Build concepts progressively
Include interactive Sandpack examples
Use established analogies consistently
Place Pitfalls AFTER explaining concepts
Invite experimentation with "Try..." phrases

Don't:

Use "simple", "easy", "just", or time estimates
Reference concepts not yet introduced
Skip required components for page type
Use passive voice without reason
Place Pitfalls before teaching the concept
Use --- dividers between sections
Create unnecessary abstraction in examples
Place consecutive Pitfalls or Notes without separating prose (combine or separate)

Critical Rules

All headings require IDs: ## Title {/title-id/}
Chapter intros use isChapter={true} and <LearnMore>
Tutorial pages omit YouWillLearn/Recap/Challenges
Problem-first teaching: Show broken → explain → fix
No consecutive Pitfalls/Notes: See /docs-components Callout Spacing Rules

For component patterns, invoke /docs-components . For Sandpack patterns, invoke /docs-sandpack .