Chapter Content Generator

Chapter Content Generator

Overview

This skill generates detailed educational content for individual textbook chapters, transforming chapter outlines (title, summary, concept list) into comprehensive learning material with appropriate reading level, rich visual elements, and interactive components. The skill is designed to run after the book-chapter-generator skill has created the chapter structure.

When to Use This Skill

Use this skill when:

• The book-chapter-generator skill has created chapter directories with index.md files
• A chapter index.md contains: title, summary, and concepts covered list
• Detailed chapter content needs to be generated
• Content should be adapted to a specific reading level (junior high, senior high, college, graduate)
• Rich non-text elements (diagrams, MicroSims, infographics) are desired

Do NOT use this skill when:

• Chapter structure hasn't been created yet (use book-chapter-generator first)
• Content already exists and just needs editing (use Edit tool directly)
• Generating other types of content (prompts, glossaries, etc.)

Workflow

Step 1: Verify Chapter File Exists

Verify that the input chapter name or path to the chapter file is present.

Expected input format:

• Chapter name: "01-intro-to-itil-and-config-mgmt" or "Chapter 1"
• Full path: "/docs/chapters/01-intro-to-itil-and-config-mgmt/index.md"
• Relative path: "chapters/01-intro-to-itil-and-config-mgmt/index.md"

Chapter directory structure:

/docs/chapters/NN-lowercase-name/index.md

Where:

• NN = Two-digit chapter number with leading zero (e.g., "01", "07", "12")
• lowercase-name = URL-friendly lowercase name with dashes, no spaces

Actions: 1. If chapter name is provided, search for matching directory in /docs/chapters/ 2. If path is provided, verify file exists at that location 3. If file not found, ask user to specify correct chapter name or path 4. Read the chapter index.md file

Step 2: Verify Chapter Content is Correct

Open the chapter file and check for required elements.

Required elements:

1. Title in header 1 (# Title) 2. Summary in level 2 header (## Summary) 3. Concepts Covered in level 2 header (## Concepts Covered) with numbered list

Actions: 1. Parse the chapter index.md file 2. Extract:

• Chapter title
• Summary text
• List of concepts covered (numbered list)

3. If any element is missing, ask user to provide the content as text 4. Store concepts list for verification in Step 5

Step 3: Get the Reading Level

Extract the grade reading level from the /docs/course-description.md file.

Reading level indicators in course description:

• "junior-high", "junior high", "grades 7-9", "middle school" → Junior High
• "senior-high", "senior high", "grades 10-12", "high school" → Senior High
• "college", "undergraduate", "bachelor" → College
• "graduate", "master", "masters", "master's", "PhD", "doctoral" → Graduate

Actions: 1. Read /docs/course-description.md 2. Search for reading level indicators in:

• Course title
• Target audience section
• Prerequisites section
• Course overview

3. If not found, ask user: "What grade-level should be used to generate the content?" 4. Default to Grade 10 (Senior High) if not specified

Reading level characteristics:

• Junior High (Grades 7-9): Simple sentences (12-18 words), common vocabulary, concrete examples, frequent visual aids
• Senior High (Grades 10-12): Mixed sentence complexity (15-22 words), technical vocabulary with definitions, balance of concrete and abstract
• College: Academic style (18-25 words), technical terminology, case studies, research context
• Graduate: Sophisticated prose (20-30+ words), full jargon, theoretical depth, research literature

See references/reading-levels.md for detailed guidelines on adapting content for each level.

Step 4: Generate Detailed Chapter Content

Generate comprehensive educational content based on the chapter outline, concept list, and reading level.

Content generation principles:

1. Reading level adaptation:

• Apply appropriate sentence complexity, vocabulary, and explanation style
• See references/reading-levels.md for specific guidelines

2. Concept ordering:

• Present simple concepts first, complex concepts last
• Follow natural pedagogical progression
• Do NOT necessarily follow the order in "Concepts Covered" list
• Build on previously explained concepts

3. Non-text elements:

• Goal: No more than 3 paragraphs of pure text without a non-text element.
• Use diverse element types (don't repeat the same type).
• Place special focus on interactive elements (infographics, MicroSims).
• We appropriate, render equations in LaTeX surrounded by single dollar signs.
• See the math-equations.md file in the references for proper formatting of equations.

Non-text element types:

Elements embedded directly in markdown (no <details markdown="1"> block):

1. Markdown lists (bullet or numbered) - ALWAYS put blank line before list 2. Markdown tables - ALWAYS put blank line before table

Elements requiring diagram header and <details markdown="1"> specification blocks:

3. Diagrams/drawings - System architectures, relationships, data flows 4. Interactive infographics - Clickable concept maps, progressive disclosure, hovers with definitions appearing in tooltips consistent with the glossary 5. MicroSims - p5.js simulations with interactive controls 6. Charts - Bar, line, pie charts with quantitative data 7. Timelines - Historical progression, sequential events 8. Maps - Geographic distribution with movement arrows 9. Workflow diagrams - Business processes with hover text 10. Graph data models - Entity relationships using vis-network 11. Causal Loop Diagrams - used in systems thinking and explaining causality

For each <details markdown="1"> block element, use this structure:

#### Diagram: [Brief descriptive title]

<details markdown="1">
    <summary>[Brief descriptive title]</summary>
    Type: [element-type]

    [Detailed specification following guidelines in references/content-element-types.md]

    Implementation: [Technology/approach]
</details>

Make SURE to put the level 4 header with the prefix #### Diagram: before the details. This is REQUIRED!

Specification requirements:

• Detailed enough that another skill or developer can implement without additional context
• Include all visual elements, data, labels, colors, interactions
• Specify canvas sizes, layout, default parameters
• For MicroSims: describe learning objective, controls, visual elements, behavior
• See references/content-element-types.md for complete specification guidelines for each element type

Content structure:

1. Start with introductory paragraphs connecting to chapter summary 2. Present concepts in pedagogical order (simple to complex) 3. Integrate non-text elements naturally throughout 4. Use markdown lists and tables frequently (with blank lines before them) 5. Include <details markdown="1"> blocks for complex visual/interactive elements 6. Place a level 4 markdown header before each details block ``#### Diagram: [Diagram Name]`` 6. End with summary or key takeaways section

Interactive elements emphasis:

• Prioritize MicroSims and infographics that enable:
• Student interaction tracking
• Progress gauging
• Personalized content recommendations
• Each interactive element should have clear Learning objectives:
• Reference a section of the 2001 Bloom Taxonomy when you describe a learning objective:
• Remembering: Recalling facts, terms, basic concepts, and answers without necessarily understanding their meaning.
• Understanding: Explaining ideas or concepts, demonstrating comprehension by summarizing or rephrasing information.
• Applying: Using acquired knowledge to solve problems in new or unfamiliar situations.
• Analyzing: Breaking down information into parts to understand its structure and relationships, and drawing comparisons.
• Evaluating: Making judgments about information based on set criteria or standards, requiring critical thinking and justification.
• Creating: Producing new or original work by combining elements to form a novel whole or solution.

Step 5: Verify Completeness

After generating chapter content, verify all concepts have been covered.

Verification process: 1. Review the generated content 2. Check that each concept from "Concepts Covered" list appears in the content 3. Create a checklist showing which concepts were covered 4. If any concepts missing:

• Add content covering those concepts
• Integrate them naturally into existing structure

5. Update the chapter index.md file with the complete generated content 6. Make Absolutely Sure that the content has been written to the chapter index.md file. Do a word count to make sure that *ALL the content is present and that the TODO has been removed.

Actions:

• Replace the "TODO: Generate Chapter Content" placeholder with generated content
• Keep the existing title, summary, concepts list, and prerequisites sections
• Add the new detailed content after the prerequisites section

Step 6: Report Summary to User

Provide a concise summary of the content generation results.

Report should include: 1. Confirmation that chapter content has been generated 2. Reading level used 3. Word count or approximate length 4. Count of non-text elements by type:

• Markdown lists: X
• Markdown tables: X
• Diagrams: X
• Infographics: X
• MicroSims: X
• Charts: X
• Timelines: X
• Maps: X
• Workflows: X
• Graph models: X

5. Number of interactive elements requiring skill execution 6. Confirmation that all concepts were covered

Example report:

✅ Chapter content generated successfully!

Chapter: 01-intro-to-itil-and-config-mgmt
Reading level: Graduate
Content length: ~3,500 words

Non-text elements:
- 6 markdown lists
- 3 markdown tables
- 2 diagrams (CMDB architecture, ITIL process flow)
- 1 interactive timeline (ITIL evolution)
- 1 MicroSim (Configuration drift simulator)
- 1 workflow diagram (Change management process)

Interactive elements: 2 (timeline, MicroSim)
Skills required: 2 (microsim-p5 for MicroSim, infographic-generator for timeline)

All 20 concepts covered: ✓

Resources

This skill includes reference files that provide detailed guidelines for content generation:

references/content-element-types.md

Comprehensive specifications for all non-text element types (3-10 above). Includes:

• When to use each element type
• Required information for specifications
• Implementation approaches
• Example specifications in <details markdown="1"> block format
• Place a level 4 Diagram header before each details element

#### Diagram: [Diagram Name]

Load this reference when generating content to ensure proper specification of diagrams, MicroSims, infographics, charts, timelines, maps, workflows, and graph models.

references/reading-levels.md

Detailed guidelines for adapting content to different reading levels. Includes:

• Sentence structure and length guidelines
• Vocabulary choices
• Explanation styles
• Example complexity
• Assumed background knowledge
• Example text at each level

Load this reference when determining how to write content at the appropriate reading level.

Best Practices

1. Always read references: Load references/content-element-types.md and references/reading-levels.md before generating content

2. Maintain blank lines: Always place blank line before markdown lists and tables (MkDocs requirement)

3. Pedagogical ordering: Don't feel constrained by concept list order - teach concepts in the most effective sequence

4. Visual variety: Mix different types of non-text elements rather than using the same type repeatedly

5. Interactive emphasis: Prioritize MicroSims and infographics that enable student engagement tracking

6. Detailed specifications: Make <details markdown="1"> blocks comprehensive enough for implementation without additional context

7. Concept integration: Weave concepts together naturally rather than treating them as isolated topics

8. Appropriate depth: Match explanation depth to reading level (more scaffolding for junior high, more theory for graduate)

9. Verification: Always check that all concepts from "Concepts Covered" list appear in generated content

10. Consistent style: Maintain consistent voice, terminology, and visual style throughout chapter

Content Element Types for Textbook Chapters

This reference describes the various non-pure-text content elements that can be used to break up textbook content and enhance learning. Each element type should be specified in <details markdown="1"> blocks when generating chapter content.

Element Types Overview

The goal is to have no more than three paragraphs of pure text without incorporating one of these elements.

1. Markdown Lists

Type identifier: markdown-list

When to use:

• Enumerating key points, features, or characteristics
• Presenting step-by-step procedures
• Listing examples or categories

Implementation: Embed directly in markdown content (no <details markdown="1"> block needed)

Requirements:

• ALWAYS place a blank line before the list
• Use numbered lists for sequences or ordered items
• Use bullet lists for unordered collections

Example:

The following are key characteristics of graph databases:

- Native graph storage
- Constant-time traversals
- Flexible schema

2. Markdown Tables

Type identifier: markdown-table

When to use:

• Comparing features across multiple dimensions
• Presenting structured data
• Showing before/after comparisons

Implementation: Embed directly in markdown content (no <details markdown="1"> block needed)

Requirements:

• ALWAYS place a blank line before the table
• Use clear, concise column headers
• Keep cell content brief
• Ensure proper markdown table syntax

Example:

Here is a comparison of database types:

| Feature | RDBMS | Graph Database |
|---------|-------|----------------|
| Schema | Rigid | Flexible |
| Joins | Required | Native traversal |
| Query Speed (multi-hop) | Slow | Fast |

3. Diagrams and Drawings

Type identifier: diagram

When to use:

• Illustrating system architectures
• Showing relationships between components
• Explaining abstract concepts visually
• Depicting data flows or processes

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Purpose of the diagram
• What components/elements should be shown
• How elements are connected or related
• Suggested visual style (flowchart, network diagram, block diagram, etc.)
• Key labels and annotations
• Color scheme if relevant

Example specification:

<details markdown="1">
    <summary>CMDB Architecture Diagram</summary>
    Type: diagram

    Purpose: Show the traditional CMDB architecture with RDBMS foundation

    Components to show:
    - CMDB Application Layer (top)
    - Business Logic Layer (middle)
    - RDBMS Storage Layer (bottom)
    - Multiple "CI Tables" within RDBMS layer
    - Relationship tables connecting CI tables

    Connections:
    - Vertical arrows showing data flow from app to storage
    - Horizontal arrows between relationship tables and CI tables

    Style: Block diagram with layered architecture

    Labels:
    - "Configuration Items (CIs)" on tables
    - "Relationships" on junction tables
    - "Foreign Keys" on connection arrows

    Color scheme: Blue for application layers, orange for database layer
</details>

4. Interactive Infographics

Type identifier: infographic

When to use:

• Presenting statistical information visually
• Creating clickable concept maps
• Building progressive disclosure interfaces
• Showing hierarchical information

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Purpose and main message
• Visual layout and organization
• Interactive elements (hovers, clicks, reveals)
• Data to be displayed
• Color coding or visual hierarchy
• Responsive behavior

Example specification:

<details markdown="1">
    <summary>ITIL Framework Evolution Interactive Timeline</summary>
    Type: infographic

    Purpose: Show the evolution of ITIL from version 1 (1990) through current version, with clickable details

    Layout: Horizontal timeline with major milestones

    Milestones:
    - 1990: ITIL v1 (31 books)
    - 2001: ITIL v2 (7 books)
    - 2007: ITIL v3 (5 books, lifecycle approach)
    - 2011: ITIL 2011 (update to v3)
    - 2019: ITIL 4 (value-driven service management)

    Interactive elements:
    - Hover over each milestone to see key changes
    - Click to expand full details panel
    - Hover over connecting lines to see transition challenges

    Visual style: Modern timeline with circular nodes for milestones
    Color scheme: Red gradient getting darker for newer versions

    Implementation: HTML/CSS/JavaScript with SVG timeline
</details>

5. MicroSims (p5.js Simulations)

Type identifier: microsim

When to use:

• Demonstrating dynamic behavior
• Allowing students to experiment with parameters
• Visualizing algorithms or processes
• Showing cause-and-effect relationships

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Learning objective (what concept is being taught)
• Visual elements in the simulation
• Interactive controls (sliders, buttons, inputs)
• Default parameter values
• What happens when parameters change
• Canvas layout (drawing area + controls area)
• Animation or static visualization

Example specification:

<details markdown="1">
    <summary>Graph Traversal Visualization MicroSim</summary>
    Type: microsim

    Learning objective: Demonstrate the difference between depth-first search (DFS) and breadth-first search (BFS) in graph traversal

    Canvas layout (800x600px):
    - Left side (600x600): Drawing area showing a graph network
    - Right side (200x600): Control panel

    Visual elements:
    - 15 nodes arranged in a tree-like structure
    - Edges connecting nodes
    - Start node (green)
    - Current node (yellow)
    - Visited nodes (blue)
    - Unvisited nodes (gray)

    Interactive controls:
    - Dropdown: Select algorithm (DFS or BFS)
    - Button: "Start Traversal"
    - Button: "Reset"
    - Slider: Animation speed (50-1000ms per step)
    - Display: Node visit order as a list

    Default parameters:
    - Algorithm: DFS
    - Animation speed: 500ms
    - Start node: Node 1

    Behavior:
    - When "Start Traversal" clicked, animate the selected algorithm
    - Highlight current node in yellow
    - Mark visited nodes in blue
    - Display visit order in right panel
    - Show queue/stack state for educational purposes

    Implementation notes:
    - Use p5.js for rendering
    - Store graph as adjacency list
    - Implement both DFS (recursive/stack) and BFS (queue)
    - Use frameCount for animation timing
</details>

6. Charts (Bar, Line, Pie)

Type identifier: chart

When to use:

• Presenting quantitative data
• Showing trends over time
• Comparing values across categories
• Illustrating proportions or distributions

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Chart type (bar, line, pie, scatter, etc.)
• Data to be plotted (specific values or representative data)
• Axis labels and units
• Title and legend
• Color scheme
• Key insights to highlight

Example specification:

<details markdown="1">
    <summary>Query Performance Comparison: RDBMS vs Graph Database</summary>
    Type: chart

    Chart type: Bar chart

    Purpose: Show performance degradation of RDBMS multi-hop queries compared to constant-time graph traversals

    X-axis: Number of hops (1, 2, 3, 4, 5)
    Y-axis: Query response time (milliseconds, logarithmic scale)

    Data series:
    1. RDBMS (orange bars):
       - 1 hop: 10ms
       - 2 hops: 150ms
       - 3 hops: 2,500ms
       - 4 hops: 45,000ms
       - 5 hops: 780,000ms (timed out)

    2. Graph Database (gold bars):
       - 1 hop: 5ms
       - 2 hops: 8ms
       - 3 hops: 12ms
       - 4 hops: 15ms
       - 5 hops: 18ms

    Title: "Multi-Hop Query Performance: RDBMS vs Graph Database"
    Legend: Position top-right

    Annotations:
    - Arrow pointing to RDBMS 5-hop bar: "Query timed out after 13 minutes"
    - Arrow pointing to graph DB series: "Constant-time traversal"

    Implementation: Chart.js or similar JavaScript library
</details>

7. Timeline

Type identifier: timeline

When to use:

• Showing historical progression
• Illustrating project phases
• Demonstrating evolution of concepts
• Presenting sequential events

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Time period covered
• Major events/milestones with dates
• Visual style (horizontal/vertical, linear/branching)
• Detail level for each event
• Color coding or visual grouping
• Interactive features if applicable

Example specification:

<details markdown="1">
    <summary>Evolution of Configuration Management Timeline</summary>
    Type: timeline

    Time period: 1980-2025

    Orientation: Horizontal

    Events:
    - 1980: Military configuration management practices established
    - 1990: ITIL v1 released (31 books including Configuration Management)
    - 1995: First commercial CMDB implementations
    - 2001: ITIL v2 consolidates CM practices
    - 2005-2010: "CMDB crisis" - high failure rates reported
    - 2012: Neo4j gains traction for IT dependency management
    - 2015: Observability tools (Dynatrace, etc.) begin automated discovery
    - 2018: Graph-based CMDB alternatives emerge
    - 2020: COVID pandemic accelerates digital transformation
    - 2023: AI-assisted IT management graphs
    - 2025: Real-time graph-based IT management becomes standard

    Visual style: Horizontal timeline with alternating above/below placement

    Color coding:
    - Red: ITIL/traditional CMDB era (1990-2010)
    - Orange: Transition period (2010-2015)
    - Gold: Graph database adoption (2015-2020)
    - Green: Modern AI-enhanced approaches (2020+)

    Interactive features:
    - Hover to see detailed description
    - Click to expand with images/screenshots from that era
</details>

8. Maps with Movement Arrows

Type identifier: map

When to use:

• Showing geographic distribution
• Illustrating data flows across regions
• Demonstrating adoption patterns
• Visualizing network topologies

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Geographic scope (world, region, country)
• Locations to mark
• Directional flows or connections
• Data being represented
• Legend and labels
• Color scheme
• Interactive features

Example specification:

<details markdown="1">
    <summary>GDPR Data Flow Compliance Map</summary>
    Type: map

    Geographic scope: World map focusing on EU and major trading partners

    Purpose: Illustrate data flow restrictions under GDPR

    Locations:
    - European Union (highlighted in blue)
    - United States (highlighted in orange)
    - United Kingdom (highlighted in purple)
    - Asia-Pacific data centers (marked with icons)

    Data flows (arrows):
    - Green arrows: Permitted flows (within EU)
    - Yellow arrows: Conditional flows (EU to UK, adequacy decision)
    - Red arrows: Restricted flows (EU to US, requires safeguards)
    - Dotted arrows: Data center backup routes

    Labels:
    - "GDPR Protected Territory"
    - "Adequacy Decision Required"
    - "Standard Contractual Clauses (SCCs) Required"

    Legend:
    - Arrow colors and meanings
    - Icon explanations (data center, user, cloud)

    Interactive features:
    - Hover over arrows to see data transfer requirements
    - Click regions to see compliance details
</details>

9. Workflow Diagrams with Hover Text

Type identifier: workflow

When to use:

• Illustrating business processes
• Showing decision trees
• Explaining system interactions
• Demonstrating procedural steps

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Process name and purpose
• Steps in the workflow (with descriptions)
• Decision points and branches
• Start and end states
• Hover text content for each element
• Visual style (swimlanes, flowchart, BPMN)
• Roles or systems involved

Example specification:

<details markdown="1">
    <summary>Change Management Workflow with Impact Analysis</summary>
    Type: workflow

    Purpose: Show the change management process using graph-based impact analysis

    Visual style: Flowchart with decision diamonds and process rectangles

    Steps:
    1. Start: "Change Request Submitted"
       Hover text: "Engineer submits change request for system update"

    2. Process: "Query IT Management Graph"
       Hover text: "Run graph traversal to identify all downstream dependencies"

    3. Process: "Calculate Blast Radius"
       Hover text: "Determine which services, applications, and business functions are affected"

    4. Decision: "Risk Level?"
       Hover text: "Based on blast radius: Low (<10 services), Medium (10-50), High (>50)"

    5a. Process: "Auto-Approve" (if Low risk)
        Hover text: "Changes affecting fewer than 10 services are auto-approved"

    5b. Process: "Manager Review" (if Medium risk)
        Hover text: "Changes affecting 10-50 services require manager approval"

    5c. Process: "CAB Review" (if High risk)
        Hover text: "Changes affecting >50 services require Change Advisory Board review"

    6. Process: "Notify Affected Teams"
       Hover text: "Automated notifications sent to all teams managing dependent services"

    7. End: "Change Approved"
       Hover text: "Change ticket updated and implementation scheduled"

    Color coding:
    - Blue: Data/query steps
    - Yellow: Decision points
    - Green: Approval outcomes
    - Orange: Communication steps

    Swimlanes:
    - Requester
    - IT Management Graph System
    - Approval Authority
    - Affected Teams
</details>

10. Graph Data Models (vis-network)

Type identifier: graph-model

When to use:

• Showing entity relationships
• Demonstrating graph database schemas
• Illustrating dependency networks
• Visualizing knowledge graphs

Implementation: Use <details markdown="1"> block with specification

Required information in description:

• Node types and their properties
• Edge types and their properties
• Sample data to display
• Layout algorithm (force-directed, hierarchical, circular)
• Visual styling (colors, shapes, sizes)
• Interactive features (zoom, drag, click, hover)
• Legend explaining node/edge types

Example specification:

<details markdown="1">
    <summary>IT Management Graph Data Model</summary>
    Type: graph-model

    Purpose: Illustrate the node and relationship types in a typical IT management graph

    Node types:
    1. Business Service (pink circles)
       - Properties: name, owner, SLA_target
       - Example: "Customer Portal"

    2. Application (light blue squares)
       - Properties: name, version, technology_stack
       - Example: "Web Server v2.1"

    3. Infrastructure (gray diamonds)
       - Properties: name, type, location
       - Example: "Server-001 (VM)"

    4. Data Store (orange cylinders)
       - Properties: name, type, size_gb
       - Example: "Customer DB"

    Edge types:
    1. DEPENDS_ON (solid black arrows)
       - Properties: criticality (high/medium/low)
       - Example: Business Service → Application

    2. HOSTS (dashed blue arrows)
       - Properties: deployment_type
       - Example: Infrastructure → Application

    3. CONNECTS_TO (dotted green arrows)
       - Properties: protocol, port
       - Example: Application → Data Store

    Sample data:
    - Customer Portal (Business Service)
      ├─ DEPENDS_ON → Web Application (Application)
      │  ├─ HOSTS ← VM-Server-001 (Infrastructure)
      │  └─ CONNECTS_TO → Customer DB (Data Store)
      └─ DEPENDS_ON → API Gateway (Application)
         └─ CONNECTS_TO → Auth Service DB (Data Store)

    Layout: Hierarchical with business services at top

    Interactive features:
    - Hover node: Show properties
    - Click node: Highlight all connected nodes
    - Double-click: Expand/collapse dependencies
    - Zoom: Mouse wheel
    - Pan: Click and drag background

    Visual styling:
    - Node size based on number of connections (degree)
    - Edge thickness based on criticality
    - Highlight critical path in red when node selected

    Legend:
    - Node shapes and their meanings
    - Edge styles and their meanings
    - Color coding explanation

    Implementation: vis-network JavaScript library
    Canvas size: 800x600px
</details>

General Guidelines for All Content Elements

1. Progressive Complexity: Place simpler elements earlier in the chapter, more complex ones later 2. Concept Coverage: Ensure elements connect back to concepts listed in "Concepts Covered" 3. Learning Objectives: Every element should serve a clear pedagogical purpose 4. Accessibility: Provide text alternatives for visual elements 5. Consistency: Use similar visual styles and color schemes throughout a chapter 6. Interactivity: Favor interactive elements (infographics, MicroSims) that enable student engagement tracking 7. Balance: Mix different types of elements rather than using the same type repeatedly

Details Block Template

For any element requiring specification (types 3-10), use this template:

<details markdown="1">
    <summary>Brief descriptive title</summary>
    Type: [element-type]

    Purpose: [What educational goal does this serve?]

    [Element-specific details as outlined above]

    Implementation: [Technology/approach to be used]
</details>

The specification should be detailed enough that another skill or developer can implement the element without additional context.

Rendering Equations in Mkdocs

It is easy to add complex equations to any chapter content. Our intelligent textbooks all come configured with the MathJax libraries installed so that you just put LeTeX directly in the markdown files surrounded by dollar signs $. You do not need to put in backslashes before the $ or ..

Equation Rendering Rules

1. Always put name of the equation in markdown level 4 header. This allows us to send a link to each equation in a chat or email. 2. Within the body text, render equation in LaTeX format on a line with blank lines before and after the LaTeX equation. 3. Surround the equation with single dollar signs in front and in back of the LaTeX strings. 4. For each variable in the equation, add a "where:" that defines each variable. 5. Put blank lines around the word "where:" and list of variables. 6. Follow the "where" with a markdown list of the variables. 7. Wrap the variables names in single dollar signs within the definitions.

Here are two examples of the format I want.

Slope and Intercept

$y = m * x + b$

where:

• $y$ is the vertical axis
• $x$ is the horizontal axis
• $m$ is the slope
• $b$ is the intercept

Point-Slope Form

The point-slope form of a line passing through point $(x_1, y_1)$ with slope $m$:

$$y - y_1 = m(x - x_1)$$

Standard Form of a Quadratic

The standard form of a quadratic equation:

$ax^2 + bx + c = 0$

where:

• $a is the coefficient of the square of x
• $b is the coefficient of x
• $c is a constant
• $a \neq 0$.

The Quadratic Formula

The quadratic formula for solving $ax^2 + bx + c = 0$:

$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Vertex Form of the Quadric Function

The vertex form of a quadratic function:

$y = a(x - h)^2 + k$

where:

• $(h, k)$ is the vertex of the parabola.

Area of a Circle

$A = 2\pi r^2$

where:

• $A$ is the area of the circle
• $r$ is the radius

Ohm's Law

$V = I R$

where:

• $V$ is the voltage across the resistor
• $I$ is the current through the resistor
• $R$ is the resistance

Kirchhoff's Voltage Law (KVL)

$\sum_{k=1}^{n} V_k = 0$

where:

• $V_k$ is the voltage across the $k$th element in the loop
• $n$ is the number of elements in the loop

Complex Power

$S = V_{\text{RMS}} I_{\text{RMS}}^\* = P + j Q$

where:

• $S$ is the complex power
• $V_{\text{RMS}}$ is the RMS voltage
• $I_{\text{RMS}}^\*$ is the complex conjugate of the RMS current
• $P$ is the real power
• $Q$ is the reactive power
• $j$ is the imaginary unit ($j = \sqrt{-1}$)

Reading Level Guidelines for Textbook Content

This reference provides guidance on adjusting textbook content for different reading levels based on grade level or educational context.

Reading Level Overview

Reading level affects:

• Sentence complexity and length
• Vocabulary choice
• Explanation depth
• Example complexity
• Assumed background knowledge

Grade Level Categories

Junior High (Grades 7-9)

Target age: 12-15 years old

Sentence structure:

• Average sentence length: 12-18 words
• Use primarily simple and compound sentences
• Limit complex sentences with multiple clauses
• One main idea per sentence

Vocabulary:

• Use common, everyday words when possible
• Introduce technical terms gradually with clear definitions
• Provide synonyms or simpler explanations in parentheses
• Avoid jargon unless essential and well-explained

Explanation style:

• Use concrete examples and analogies to familiar experiences
• Break complex ideas into smaller steps
• Repeat key concepts in different ways
• Use frequent summaries

Example complexity:

• Real-world examples from students' daily lives
• Simple scenarios with few variables
• Step-by-step walkthroughs
• Visual aids are essential

Assumed knowledge:

• Basic computer literacy
• Simple math (arithmetic, basic algebra)
• General science concepts
• No specialized domain knowledge

Example text (Junior High):

Graph databases store information differently than traditional databases. Think of a social media network like Instagram. When you want to see who your friends' friends are, a graph database can find this quickly. It follows the connections between people, just like you might follow arrows on a map. Traditional databases would need to look through many separate lists to find the same information, which takes much longer.

Senior High (Grades 10-12)

Target age: 15-18 years old

Sentence structure:

• Average sentence length: 15-22 words
• Mix of simple, compound, and some complex sentences
• Can handle sentences with multiple clauses if well-structured
• Vary sentence length for emphasis and flow

Vocabulary:

• Introduce technical vocabulary with definitions
• Use domain-specific terms appropriately
• Expect familiarity with academic language
• Build vocabulary progressively throughout chapter

Explanation style:

• Balance concrete examples with abstract concepts
• Introduce theoretical frameworks
• Connect to broader patterns and principles
• Include some optional depth for advanced students

Example complexity:

• Mix of real-world and somewhat abstract scenarios
• Multi-step problems with several variables
• Introduction to industry contexts
• Diagrams supplement but don't replace text explanations

Assumed knowledge:

• Computer literacy and basic programming concepts
• Algebra and basic data structures
• Scientific method and analytical thinking
• Some awareness of technology industry

Example text (Senior High):

Graph databases employ a fundamentally different storage paradigm compared to relational databases. In a relational system, discovering multi-hop relationships—such as friends-of-friends in a social network—requires expensive JOIN operations across multiple tables. Each additional hop compounds the performance penalty. Graph databases, by contrast, use index-free adjacency, where each node directly references its connected nodes. This architectural choice enables constant-time traversals regardless of depth, making them ideal for applications requiring real-time relationship queries.

College/University (Undergraduate) or Professional Development

Target age: 18-22 years old

Sentence structure:

• Average sentence length: 18-25 words
• Full range of sentence structures including complex constructions
• Multiple clauses and embedded ideas are acceptable
• Academic writing style with professional tone

Vocabulary:

• Use technical terminology freely with concise definitions
• Assume familiarity with field-standard concepts
• Introduce specialized jargon from industry and research
• Reference related concepts without always re-explaining

Explanation style:

• Balance between practical and theoretical
• Discuss multiple perspectives and approaches
• Include research findings and case studies
• Connect to broader academic and professional contexts
• Expect critical thinking and analysis

Example complexity:

• Complex real-world scenarios from industry
• Multi-faceted problems requiring integration of concepts
• Case studies with ambiguous solutions
• Technical specifications and formal notations

Assumed knowledge:

• Programming experience in multiple languages
• Data structures and algorithms
• Database fundamentals (from prerequisite courses)
• Systems thinking and architectural concepts
• Business and organizational contexts

Example text (College):

Graph databases address the impedance mismatch between relational storage and relationship-intensive queries through native graph storage architectures. Unlike relational systems where foreign key relationships are represented implicitly through join tables, graph databases materialize relationships as first-class entities with their own properties and directionality. This design enables index-free adjacency, where traversing from one node to connected nodes operates in O(1) time regardless of graph size. For IT management applications requiring multi-hop transitive dependency analysis—such as calculating blast radius or performing root cause analysis—this architectural advantage translates to orders of magnitude performance improvements compared to equivalent recursive SQL queries.

Graduate Level (Master's/PhD)

Target age: 22+ years old

Sentence structure:

• Average sentence length: 20-30+ words
• Sophisticated sentence structures with multiple embedded clauses
• Dense information packing appropriate for expert audience
• Academic and professional writing standards

Vocabulary:

• Full technical terminology without simplified definitions
• Domain-specific jargon and acronyms used freely
• Reference to research literature and theoretical frameworks
• Assume reader can infer meanings from context

Explanation style:

• Theoretical depth with formal analysis
• Critical evaluation of approaches and trade-offs
• Integration across multiple domains and disciplines
• Discussion of research frontiers and open problems
• Emphasis on practical application in complex organizational contexts

Example complexity:

• Complex multi-stakeholder scenarios
• Problems requiring synthesis of theory and practice
• Industry case studies with detailed technical and business contexts
• Formal specifications, algorithms, and mathematical models
• Discussion of research methodologies and empirical findings

Assumed knowledge:

• Significant professional or academic experience
• Deep understanding of database systems and architectures
• Enterprise systems and organizational contexts
• Research methods and critical analysis
• Relevant industry standards and frameworks

Example text (Graduate):

Graph-native storage architectures fundamentally address the O(n) table scan problem inherent in relational approaches to transitive closure queries by materializing relationships as pointer-based adjacency structures. This design paradigm shift—from value-based foreign key joins requiring B-tree index lookups to direct pointer traversal—enables constant-time neighbor access patterns characteristic of index-free adjacency. For enterprise IT management graphs where dependency chains routinely span 5-10 hops, this architectural choice yields 2-3 orders of magnitude performance improvements in real-time impact analysis queries. However, this optimization introduces trade-offs in write amplification during edge-intensive updates and requires careful consideration of consistency models in distributed deployments. Contemporary implementations such as Neo4j's native graph storage employ write-ahead logging and MVCC for ACID guarantees, while alternatives like JanusGraph leverage distributed backend stores (Cassandra, HBase) accepting eventual consistency in exchange for horizontal scalability.

Adapting Content for Reading Level

Simplifying for Lower Levels

When adapting content for lower reading levels:

1. Break long sentences: Split complex sentences into 2-3 shorter ones 2. Replace technical terms: Use common words or provide analogies 3. Add examples: Increase ratio of examples to explanations 4. Increase visual aids: Use more diagrams, charts, and illustrations 5. Remove abstraction: Focus on concrete, practical applications 6. Add definitions: Define terms in context, not just in glossary 7. Use active voice: Avoid passive constructions when possible 8. Add summaries: Frequent recaps and reviews

Elevating for Higher Levels

When adapting content for higher reading levels:

1. Increase information density: Pack more concepts per sentence 2. Use technical vocabulary: Employ domain-specific terminology 3. Add depth: Include theoretical foundations and research context 4. Reduce redundancy: Assume concepts stick on first explanation 5. Increase abstraction: Connect to broader patterns and frameworks 6. Add complexity: Multi-faceted examples with nuance 7. Reference literature: Cite research, standards, and best practices 8. Challenge assumptions: Present multiple perspectives and trade-offs

Content Generation Strategy by Reading Level

For All Levels

Regardless of reading level:

• Start with simpler concepts, progress to complex
• Use concrete examples before abstract principles
• Provide visual representations of key concepts
• Include interactive elements (MicroSims, infographics)
• Summarize key takeaways at end of sections

Adjusting Non-Text Elements

Junior High:

• More frequent visual elements (every 2-3 paragraphs)
• Simpler diagrams with fewer components
• Interactive elements with clear, immediate feedback
• Step-by-step animations

Senior High:

• Visual elements every 3-5 paragraphs
• More detailed diagrams
• Interactive elements that encourage exploration
• Some elements requiring inference

College:

• Visual elements every 4-6 paragraphs
• Complex diagrams with multiple layers
• Interactive elements requiring parameter tuning
• Elements that demonstrate edge cases

Graduate:

• Visual elements as needed for complex concepts
• Sophisticated visualizations with research context
• Interactive elements for exploring trade-offs
• Elements demonstrating real-world complexity

Default Reading Level

When reading level is not specified, use Grade 10 (Senior High) as the default. This represents:

• Upper secondary education
• Transition between simplified and professional content
• Appropriate for self-learners and career transitioners
• Balance between accessibility and depth