aiskillstore/marketplace / skills/92bilal26/book-scaffolding
book-scaffolding
VerifiedPlan, structure, and scaffold large educational books using cognitive load management, just-in-time specification, and pedagogical best practices. Use this skill when planning multi-part, multi-chapter educational works that require narrative continuity, progressive complexity, and hands-on exercises. This skill helps create cohesive learning journeys that balance foundational scaffolding with advanced independence. Activate when tasks involve structuring books, managing cognitive load across chapters, defining part-level narratives, or coordinating multi-phase content development workflows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.1 KB |
| reference/chapter-dependencies.md | markdown | 16.0 KB |
| reference/chapter-flow-patterns.md | markdown | 15.4 KB |
| reference/content-organization.md | markdown | 16.4 KB |
| reference/structural-patterns.md | markdown | 17.9 KB |
| scripts/analyze-flow.pyexecutable | script | 16.0 KB |
| scripts/validate-structure.pyexecutable | script | 13.7 KB |
| skill-report.json | config | 54.2 KB |
| templates/book-outline-template.yml | config | 11.0 KB |
| templates/chapter-structure-template.yml | config | 15.9 KB |
reference/content-organization.md
View on GitHub# Content Organization Strategies for Technical Books
## Overview
This document provides strategies for organizing large amounts of technical content, including chunking strategies, cross-referencing patterns, indexing approaches, and techniques for managing complexity in comprehensive books.
---
## Chunking Strategies
### What is Chunking?
Chunking is the process of breaking down large amounts of information into smaller, digestible units that align with working memory limitations (typically 5-9 items per chunk).
### Chunk Size Guidelines
#### Micro Chunks (Paragraphs)
- **Size**: 3-7 sentences
- **Purpose**: Single idea or concept
- **Use**: Building block of explanations
- **Cognitive Load**: Minimal
**Example**:
```
A function is a reusable block of code that performs a specific task.
Functions help organize code and avoid repetition. In Python, you
define a function using the `def` keyword, followed by the function
name and parentheses. The code inside the function is indented and
executes only when the function is called.
```
#### Mini Chunks (Sections)
- **Size**: 3-7 paragraphs or 1-3 pages
- **Purpose**: Complete sub-topic or concept facet
- **Use**: Subsections within chapters
- **Cognitive Load**: Low to medium
**Example Sections**:
```
2.3 Function Parameters
2.3.1 Positional Parameters (2 pages)
2.3.2 Keyword Parameters (2 pages)
2.3.3 Default Values (1.5 pages)
2.3.4 Variable Arguments (*args, **kwargs) (3 pages)
```
#### Standard Chunks (Chapters)
- **Size**: 15-30 pages
- **Purpose**: Complete topic or learning module
- **Use**: Main organizational unit
- **Cognitive Load**: Medium
#### Macro Chunks (Parts)
- **Size**: 3-6 chapters or 60-150 pages
- **Purpose**: Major subject area or skill level
- **Use**: Book-level organization
- **Cognitive Load**: High (requires sustained engagement)
---
## Hierarchical Organization Patterns
### Pattern 1: Three-Level Hierarchy (Standard)
```
Book Title
├── Part I: Fundamentals
│ ├── Chapter 1: Introduction
│ │ ├── 1.1 Why Python?
│ │ ├── 1.2 Setting Up
│ │ └── 1.3 Your First Program
│ └── Chapter 2: Variables and Types
│ ├── 2.1 Understanding Variables
│ ├── 2.2 Primitive Types
│ └── 2.3 Type Conversion
└── Part II: Intermediate Topics
└── [More chapters...]
```
**Advantages**:
- Clear hierarchy (Part > Chapter > Section)
- Easy to navigate
- Standard reader expectation
**Best For**: Most technical books (10-20 chapters)
---
### Pattern 2: Four-Level Hierarchy (Comprehensive)
```
Book Title
├── Part I: Core Language
│ ├── Module 1: Basics (3 chapters)
│ │ ├── Chapter 1: Introduction
│ │ │ ├── 1.1 What is Python?
│ │ │ │ ├── 1.1.1 History
│ │ │ │ └── 1.1.2 Philosophy
│ │ │ ├── 1.2 Installation
│ │ │ └── 1.3 First Steps
│ │ └── [More chapters...]
│ └── Module 2: Data Structures (4 chapters)
└── Part II: Applications
```
**Advantages**:
- Extra organizational layer (Module) for very large books
- Finer-grained structure
- Supports progressive learning paths
**Best For**: Comprehensive textbooks (20+ chapters), university courses
**Caution**: Can be overwhelming if overused. Use modules sparingly.
---
### Pattern 3: Flat Hierarchy (Modular)
```
Book Title
├── Chapter 1: List Comprehensions
│ ├── 1.1 Syntax
│ ├── 1.2 Filtering
│ └── 1.3 Examples
├── Chapter 2: Decorators
│ ├── 2.1 What Are Decorators?
│ ├── 2.2 Writing Decorators
│ └── 2.3 Common Patterns
└── [More chapters...]
```
**Advantages**:
- No parts (all chapters at same level)
- Maximum flexibility (read in any order)
- Simpler navigation
**Best For**: Cookbooks, reference guides, advanced topic collections
---
## Cross-Referencing Techniques
### Types of Cross-References
#### Forward References (Foreshadowing)
Point to future content to build anticipation or contextualize current simplifications.
**Example**:
```
For now, we'll use a simple approach. In Chapter 8, we'll explore
more robust error handling using exceptions.
```
**Guidelines**:
- Use sparingly (don't overwhelm with "we'll cover this later")
- Provide just enough context for current understanding
- Always include chapter number for easy lookup
- Consider "Advanced Topic" sidebars for immediate elaboration
#### Backward References (Recaps)
Remind readers of previously covered material.
**Example**:
```
Recall from Chapter 3 that functions can accept default parameters:
def greet(name="World"):
return f"Hello, {name}"
We'll use this technique here to make our API more flexible.
```
**Guidelines**:
- Include brief recap (don't just say "see Chapter 3")
- Provide enough context to continue without backtracking
- Use when concept is essential to current discussion
- Link to specific section, not just chapter
#### Lateral References (Related Topics)
Point to parallel or alternative content.
**Example**:
```
Dictionaries are one way to organize data. For ordered collections,
see Chapter 4 (Lists). For unique values, see Chapter 6 (Sets).
```
**Guidelines**:
- Help readers see relationships between concepts
- Useful for "see also" references
- Don't overdo it (too many references are distracting)
- Consider comparison tables instead of prose references
---
### Cross-Reference Formats
#### In-Text Parenthetical
```
Functions can be passed as arguments (see Section 5.3, "Higher-Order Functions").
```
#### Margin Notes
```
Main text here... → See Chapter 8 for
exception handling
```
#### Sidebars
```
┌──────────────────────────────────┐
│ RELATED TOPIC │
│ │
│ For a different approach using │
│ generators, see Chapter 10. │
└──────────────────────────────────┘
```
#### End-of-Section References
```
Further Reading:
- Chapter 7: Advanced Function Techniques
- Appendix A: Python Built-in Functions
- Online: PEP 8 Style Guide
```
---
## Managing Complexity
### Principle 1: Progressive Disclosure
Reveal complexity incrementally rather than all at once.
**Example: Teaching Decorators**
**❌ All-at-Once (Overwhelming)**:
```
Chapter 9: Decorators
Decorators are functions that take functions as arguments and return
modified functions. They use closure, *args, **kwargs, and the @
syntax. They can be stacked, parameterized, or applied to classes...
```
**✅ Progressive Disclosure (Manageable)**:
```
Chapter 9: Decorators
9.1 The Problem: Repetitive Code
[Show repeated logging code across functions]
9.2 A Solution: Wrapper Functions
[Show manual wrapper without @ syntax]
9.3 The @ Syntax
[Introduce decorator syntax]
9.4 Writing Reusable Decorators
[Introduce *args, **kwargs for generality]
9.5 Advanced: Stacking and Parameterization
[Now that basics are solid, add complexity]
```
**Guidelines**:
- Start with "why" (motivation)
- Show simple version first
- Add features incrementally
- Each step should be usable on its own
- Complexity emerges from need, not imposed
---
### Principle 2: Concept Maps and Relationship Diagrams
Help readers see how pieces fit together.
**Example: Python Data Structures Map**
```
Data Structures
├── Sequences (ordered, indexed)
│ ├── Lists [mutable]
│ ├── Tuples [immutable]
│ └── Strings [immutable, text]
├── Mappings (key-value)
│ └── Dictionaries [mutable]
└── Sets (unique values)
├── Sets [mutable]
└── Frozensets [immutable]
```
**When to Use**:
- Chapter introductions (overview of coming topics)
- Part transitions (how chapters relate)
- Appendices (comprehensive reference maps)
**Tools**:
- Text-based diagrams (ASCII art for portability)
- Visual diagrams (for print books)
- Interactive maps (for digital editions)
---
### Principle 3: Layered Information
Present information in layers: essential, important, advanced.
**Layer 1: Essential (Must Know)**
- Core concept explanation
- Basic syntax
- Most common use case
- Minimal working example
**Layer 2: Important (Should Know)**
- Additional use cases
- Common variations
- Best practices
- Typical patterns
**Layer 3: Advanced (Nice to Know)**
- Edge cases
- Performance considerations
- Advanced techniques
- Historical context or rationale
**Presentation Strategies**:
**In-Chapter Layering**:
```
Main text: Essential (Layer 1)
Sidebar: Important details (Layer 2)
Advanced Topic box: Nice to know (Layer 3)
```
**Chapter-Level Layering**:
```
Chapter 5: Functions (Essential)
Chapter 5 Advanced Topics box: Closures and Scoping (Advanced)
Appendix D, Section 5: Function Internals (Advanced)
```
**Part-Level Layering**:
```
Part I: Core Concepts (Essential)
Part II: Intermediate Techniques (Important)
Part III: Advanced Topics (Advanced)
```
---
## Indexing Strategies
### Index Purpose
- Quick lookup of specific topics
- Discovery of related topics
- Navigation to all occurrences of a concept
### Index Organization Patterns
#### Primary Entries
Main concepts, functions, keywords.
```
decorator, 145-152
@syntax, 147
chaining, 150
with parameters, 151
see also closure, higher-order functions
```
#### Inverted Entries
Multiple ways to find the same concept.
```
decorator, 145-152
...
@syntax
for decorators, 147
for property, 203
```
#### Hierarchical Entries
Parent-child concept relationships.
```
functions, 45-68
arguments
keyword, 54
positional, 50
variable-length (*args), 57
defining, 45
docstrings, 63
return values, 60
```
#### Cross-References
Connect related concepts.
```
mutable types, 78-82
see list, dict, set
list, 85-102
see also tuple, sequence types
```
#### Code Symbols
Special handling for code elements.
```
__init__ (method), 134
see also constructor, initialization
* (asterisk)
in imports, 112
unpacking operator, 156
variable arguments (*args), 57
```
---
### Index Best Practices
1. **Be Comprehensive**: Index every significant concept, not just chapter topics
2. **Multiple Entry Points**: Different readers think of topics differently
3. **Bold for Definitions**: Make primary explanations stand out
4. **Italics for Examples**: Show where to find code examples
5. **Page Ranges**: Use for extended discussions (e.g., "45-52"), single pages for brief mentions
6. **Consistent Terminology**: Use same terms as in text
7. **Avoid Over-Indexing**: Don't index trivial mentions
---
## Table of Contents Design
### Basic TOC (Chapter Titles Only)
```
Contents
Preface ..................................... ix
1. Introduction to Python ................... 1
2. Variables and Types ..................... 15
3. Control Flow ............................ 35
4. Functions ............................... 58
...
```
**Advantages**: Clean, uncluttered, quick scan
**Best For**: Short books (< 10 chapters), simple structures
---
### Detailed TOC (With Sections)
```
Contents
Preface ..................................... ix
Part I: Python Fundamentals
1. Introduction to Python ................... 1
1.1 Why Python? .......................... 2
1.2 Installing Python .................... 5
1.3 Your First Program ................... 9
Exercises ............................... 13
2. Variables and Types ..................... 15
2.1 Understanding Variables ............. 16
2.2 Primitive Types ..................... 20
2.3 Type Conversion ..................... 28
Exercises ............................... 32
...
```
**Advantages**: Detailed preview, easier navigation, shows content depth
**Best For**: Most technical books, textbooks
---
### Annotated TOC (With Learning Goals)
```
Contents
Part I: Python Fundamentals
1. Introduction to Python ................... 1
What you'll learn: Install Python, write basic programs,
understand Python's philosophy
1.1 Why Python? .......................... 2
1.2 Installing Python .................... 5
1.3 Your First Program ................... 9
...
```
**Advantages**: Sets expectations, helps readers choose chapters
**Best For**: Educational books, self-study materials
---
## Content Density Management
### Concept Density Guidelines
**Low Density (Beginner-Friendly)**:
- 1-2 new concepts per section
- Extensive examples per concept
- Frequent recaps and summaries
- More pages per concept
**Example**: "Learning Python for Beginners" (300 pages, 10 core concepts)
**Medium Density (Standard)**:
- 3-5 new concepts per section
- Balanced explanation and examples
- Standard summary per chapter
- Normal pacing
**Example**: "Python Fundamentals" (400 pages, 30 core concepts)
**High Density (Advanced/Reference)**:
- 6+ concepts per section
- Concise explanations, assume background
- Minimal recaps
- More concepts per page
**Example**: "Advanced Python Techniques" (300 pages, 50+ core concepts)
---
### Managing Dense Content
**Strategy 1: Concept Highlighting**
Make new concepts visually distinct.
```
In this section, we introduce **closures**, a powerful feature where
inner functions remember variables from outer function scopes even
after the outer function has returned.
```
**Strategy 2: Running Glossary**
Define terms in margin or sidebar on first use.
```
Main text: "Decorators use closures..."
Margin:
Closure: A function that
captures variables from
its enclosing scope
```
**Strategy 3: Concept Inventory**
List new concepts at chapter start.
```
New Concepts in This Chapter:
- List comprehension
- Generator expression
- Lambda function
- Filter and map functions
```
**Strategy 4: Visual Separation**
Use whitespace, headings, rules to break up dense text.
```
2.3.1 Positional Arguments
[Content...]
---
2.3.2 Keyword Arguments
[Content...]
---
2.3.3 Default Values
[Content...]
```
---
## Appendix Organization
### Standard Appendices for Technical Books
**Appendix A: Installation and Setup**
- Step-by-step installation for different platforms
- Environment setup
- Tool configuration
- Troubleshooting
**Appendix B: Syntax Quick Reference**
- Language syntax summary
- Operator precedence table
- Built-in functions list
- Common idioms
**Appendix C: Standard Library Overview**
- Module categorization
- Most useful modules highlighted
- Brief descriptions
- Cross-references to relevant chapters
**Appendix D: Solutions to Exercises**
- Complete solutions (not just answers)
- Explanation of approach
- Alternative solutions
- Common mistakes
**Appendix E: Glossary**
- Alphabetical term definitions
- Cross-references to chapters
**Appendix F: Further Resources**
- Recommended reading
- Online resources
- Community links
- Tool recommendations
**Appendix G: Cheat Sheets**
- One-page visual references
- Common patterns
- Workflow diagrams
---
## Summary: Content Organization Principles
1. **Chunk Appropriately**: Align with working memory limits (5-9 items)
2. **Hierarchical Structure**: Clear levels (Part > Chapter > Section)
3. **Cross-Reference Strategically**: Forward, backward, and lateral references
4. **Manage Complexity**: Progressive disclosure, layered information
5. **Comprehensive Indexing**: Multiple entry points, hierarchical organization
6. **Detailed TOC**: Help readers navigate and preview content
7. **Control Density**: Match concept density to audience level
8. **Rich Appendices**: Quick reference, glossaries, resources
**Key Questions**:
- Can readers easily find what they need? (Navigation)
- Is complexity introduced gradually? (Cognitive load)
- Are relationships between concepts clear? (Mental models)
- Can the book serve reference needs? (Post-learning utility)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |