427 lines
10 KiB
Markdown
427 lines
10 KiB
Markdown
# Learning Frameworks for Technical Writing
|
|
|
|
This document provides pedagogical frameworks essential for designing effective technical books and tutorials.
|
|
|
|
## Bloom's Taxonomy
|
|
|
|
Bloom's Taxonomy provides a hierarchy of cognitive skills from simple recall to complex creation. Use it to design learning progression and create appropriate learning objectives.
|
|
|
|
### The Six Levels
|
|
|
|
#### 1. Remember (Lowest Level)
|
|
|
|
**Description:** Recall facts, terms, basic concepts
|
|
|
|
**Action Verbs:**
|
|
|
|
- List, Define, Name, Identify, Label
|
|
- Describe, Recognize, Recall, State
|
|
|
|
**Example Learning Objectives:**
|
|
|
|
- "List the main HTTP methods (GET, POST, PUT, DELETE)"
|
|
- "Identify the components of a REST API"
|
|
- "Define what JWT authentication means"
|
|
|
|
**Assessment:** Multiple choice, matching, simple recall questions
|
|
|
|
---
|
|
|
|
#### 2. Understand
|
|
|
|
**Description:** Explain ideas or concepts
|
|
|
|
**Action Verbs:**
|
|
|
|
- Explain, Describe, Summarize, Interpret
|
|
- Compare, Classify, Discuss, Paraphrase
|
|
|
|
**Example Learning Objectives:**
|
|
|
|
- "Explain how JWT tokens provide stateless authentication"
|
|
- "Describe the difference between synchronous and asynchronous code"
|
|
- "Summarize the benefits of using TypeScript over JavaScript"
|
|
|
|
**Assessment:** Short answer explanations, concept mapping
|
|
|
|
---
|
|
|
|
#### 3. Apply
|
|
|
|
**Description:** Use information in new situations
|
|
|
|
**Action Verbs:**
|
|
|
|
- Implement, Execute, Use, Apply
|
|
- Demonstrate, Build, Solve, Show
|
|
|
|
**Example Learning Objectives:**
|
|
|
|
- "Implement user authentication using Passport.js"
|
|
- "Build a REST API with CRUD operations"
|
|
- "Use async/await to handle asynchronous operations"
|
|
|
|
**Assessment:** Coding exercises, hands-on projects
|
|
|
|
---
|
|
|
|
#### 4. Analyze
|
|
|
|
**Description:** Draw connections, distinguish between parts
|
|
|
|
**Action Verbs:**
|
|
|
|
- Analyze, Compare, Contrast, Examine
|
|
- Debug, Troubleshoot, Differentiate, Investigate
|
|
|
|
**Example Learning Objectives:**
|
|
|
|
- "Analyze database query performance using EXPLAIN"
|
|
- "Debug memory leaks in Node.js applications"
|
|
- "Compare SQL vs NoSQL for specific use cases"
|
|
|
|
**Assessment:** Debugging tasks, performance analysis, case studies
|
|
|
|
---
|
|
|
|
#### 5. Evaluate
|
|
|
|
**Description:** Justify decisions, make judgments
|
|
|
|
**Action Verbs:**
|
|
|
|
- Evaluate, Assess, Critique, Judge
|
|
- Optimize, Recommend, Justify, Argue
|
|
|
|
**Example Learning Objectives:**
|
|
|
|
- "Evaluate trade-offs between different caching strategies"
|
|
- "Assess security vulnerabilities using OWASP guidelines"
|
|
- "Optimize API response times through profiling"
|
|
|
|
**Assessment:** Code reviews, architecture critiques, optimization challenges
|
|
|
|
---
|
|
|
|
#### 6. Create (Highest Level)
|
|
|
|
**Description:** Produce new or original work
|
|
|
|
**Action Verbs:**
|
|
|
|
- Design, Develop, Create, Construct
|
|
- Architect, Formulate, Author, Devise
|
|
|
|
**Example Learning Objectives:**
|
|
|
|
- "Design a scalable microservices architecture"
|
|
- "Develop a CI/CD pipeline for automated deployment"
|
|
- "Create a custom authentication system with MFA"
|
|
|
|
**Assessment:** Original projects, system design, architectural proposals
|
|
|
|
---
|
|
|
|
### Applying Bloom's to Book Structure
|
|
|
|
**Early Chapters (Remember + Understand):**
|
|
|
|
- Define terminology
|
|
- Explain core concepts
|
|
- Simple examples
|
|
|
|
**Middle Chapters (Apply + Analyze):**
|
|
|
|
- Hands-on implementation
|
|
- Debugging exercises
|
|
- Comparative analysis
|
|
|
|
**Late Chapters (Evaluate + Create):**
|
|
|
|
- Optimization challenges
|
|
- Design decisions
|
|
- Original projects
|
|
|
|
---
|
|
|
|
## Scaffolding Principles
|
|
|
|
Scaffolding provides temporary support structures that help learners achieve more than they could independently, then gradually removes support as competence grows.
|
|
|
|
### Core Principles
|
|
|
|
#### 1. Start with Concrete Examples
|
|
|
|
- Show working code first
|
|
- Use real-world scenarios
|
|
- Demonstrate before explaining theory
|
|
- Tangible results build confidence
|
|
|
|
**Example:**
|
|
|
|
```
|
|
❌ Poor: "RESTful APIs follow stateless client-server architecture..."
|
|
✅ Better: "Here's a working API endpoint. Let's see what happens when we call it, then understand why it works this way."
|
|
```
|
|
|
|
#### 2. Progress to Abstract Concepts
|
|
|
|
- After concrete understanding, introduce theory
|
|
- Connect examples to general principles
|
|
- Explain underlying concepts
|
|
- Build mental models
|
|
|
|
**Progression:**
|
|
|
|
1. Working example
|
|
2. What it does (concrete)
|
|
3. How it works (mechanism)
|
|
4. Why it works (theory)
|
|
5. When to use it (application)
|
|
|
|
#### 3. Build on Prior Knowledge
|
|
|
|
- Explicitly state prerequisites
|
|
- Reference previous chapters
|
|
- Activate existing knowledge
|
|
- Connect new to known
|
|
|
|
**Example:**
|
|
|
|
```
|
|
"In Chapter 3, we learned about promises. Async/await is syntactic sugar that makes promises easier to work with..."
|
|
```
|
|
|
|
#### 4. Gradual Complexity Increase
|
|
|
|
- Start simple, add features incrementally
|
|
- Introduce one new concept at a time
|
|
- Build up to complex examples
|
|
- Avoid overwhelming cognitive load
|
|
|
|
**Progressive Build:**
|
|
|
|
1. Basic function
|
|
2. Add error handling
|
|
3. Add logging
|
|
4. Add caching
|
|
5. Add advanced features
|
|
|
|
#### 5. Guided → Independent Practice
|
|
|
|
- Start with step-by-step tutorials
|
|
- Reduce guidance gradually
|
|
- End with independent challenges
|
|
- Build reader confidence
|
|
|
|
**Practice Progression:**
|
|
|
|
1. **Guided**: "Follow these steps exactly..."
|
|
2. **Partial guidance**: "Now implement X using the same pattern..."
|
|
3. **Independent**: "Build feature Y on your own..."
|
|
4. **Challenge**: "Design and implement Z..."
|
|
|
|
---
|
|
|
|
## Cognitive Load Management
|
|
|
|
Cognitive Load Theory explains how working memory limitations affect learning. Technical books must manage cognitive load carefully.
|
|
|
|
### Types of Cognitive Load
|
|
|
|
#### 1. Intrinsic Load
|
|
|
|
- Inherent difficulty of the material
|
|
- Cannot be reduced without changing content
|
|
- Manage by proper sequencing
|
|
|
|
**Strategy:** Break complex topics into smaller chunks
|
|
|
|
#### 2. Extraneous Load
|
|
|
|
- Unnecessary cognitive effort
|
|
- Caused by poor instruction design
|
|
- CAN and SHOULD be minimized
|
|
|
|
**Causes:**
|
|
|
|
- Confusing explanations
|
|
- Unclear code examples
|
|
- Missing context
|
|
- Poor organization
|
|
|
|
#### 3. Germane Load
|
|
|
|
- Effort required to build understanding
|
|
- Desirable difficulty
|
|
- Promotes schema construction
|
|
|
|
**Strategy:** Use exercises and practice that build understanding
|
|
|
|
### Cognitive Load Management Strategies
|
|
|
|
#### 1. Chunking Information
|
|
|
|
- Break content into digestible pieces
|
|
- Group related concepts together
|
|
- Use clear section headings
|
|
- Limit scope of each section
|
|
|
|
**Example:**
|
|
|
|
```
|
|
❌ Poor: One 40-page chapter on "Database Design"
|
|
✅ Better: Four 10-page chapters: "Schema Design", "Indexing", "Normalization", "Optimization"
|
|
```
|
|
|
|
#### 2. Progressive Disclosure
|
|
|
|
- Introduce information when needed
|
|
- Don't front-load everything
|
|
- Just-in-time teaching
|
|
- Hide complexity until required
|
|
|
|
**Example:**
|
|
|
|
```
|
|
Chapter 1: Basic SQL queries (SELECT, WHERE)
|
|
Chapter 2: Joins and relationships
|
|
Chapter 3: Advanced queries (subqueries, CTEs)
|
|
Chapter 4: Optimization and indexes
|
|
```
|
|
|
|
#### 3. Worked Examples Before Practice
|
|
|
|
- Show complete solutions first
|
|
- Explain step-by-step
|
|
- Then ask readers to practice
|
|
- Reduces cognitive load of problem-solving while learning
|
|
|
|
**Pattern:**
|
|
|
|
1. Show complete example with explanation
|
|
2. Show similar example with partial explanation
|
|
3. Ask reader to complete similar task
|
|
4. Provide independent challenge
|
|
|
|
#### 4. Dual Coding (Text + Visual)
|
|
|
|
- Use diagrams to complement text
|
|
- Code examples with visual flow diagrams
|
|
- Screenshots of results
|
|
- Reduces cognitive load by distributing across channels
|
|
|
|
**Effective Visuals:**
|
|
|
|
- Architecture diagrams
|
|
- Flow charts
|
|
- Sequence diagrams
|
|
- Database schemas
|
|
- API request/response flows
|
|
|
|
---
|
|
|
|
## Adult Learning Principles
|
|
|
|
Adult learners have specific characteristics that affect technical book design.
|
|
|
|
### Key Principles
|
|
|
|
#### 1. Adults are Self-Directed
|
|
|
|
- Provide clear learning paths
|
|
- Explain the "why" not just "what"
|
|
- Allow exploration and experimentation
|
|
- Respect prior experience
|
|
|
|
**Application:**
|
|
|
|
- Clear objectives upfront
|
|
- Optional "deep dive" sections
|
|
- Multiple approaches shown
|
|
- Encourage adaptation to needs
|
|
|
|
#### 2. Adults Need Relevance
|
|
|
|
- Real-world examples
|
|
- Practical applications
|
|
- Career relevance
|
|
- Immediate applicability
|
|
|
|
**Application:**
|
|
|
|
- Start chapters with real-world problems
|
|
- Show industry use cases
|
|
- Explain job market demand
|
|
- Provide production-ready patterns
|
|
|
|
#### 3. Adults are Problem-Oriented
|
|
|
|
- Learn best through solving problems
|
|
- Prefer practical over theoretical
|
|
- Want working solutions
|
|
- Value hands-on practice
|
|
|
|
**Application:**
|
|
|
|
- Problem-based learning approach
|
|
- Tutorials over lectures
|
|
- Working code examples
|
|
- Real projects
|
|
|
|
#### 4. Adults Bring Experience
|
|
|
|
- Acknowledge existing knowledge
|
|
- Build on prior experience
|
|
- Allow knowledge transfer
|
|
- Respect diverse backgrounds
|
|
|
|
**Application:**
|
|
|
|
- State prerequisites clearly
|
|
- Reference common experiences
|
|
- Compare to known technologies
|
|
- Provide multiple analogies
|
|
|
|
---
|
|
|
|
## Applying These Frameworks Together
|
|
|
|
### Book-Level Application
|
|
|
|
**Part I: Foundations (Bloom's: Remember + Understand)**
|
|
|
|
- Scaffolding: Concrete examples first
|
|
- Cognitive Load: Small chunks, progressive disclosure
|
|
- Adult Learning: Show relevance and practical use
|
|
|
|
**Part II: Application (Bloom's: Apply + Analyze)**
|
|
|
|
- Scaffolding: Guided tutorials with gradual independence
|
|
- Cognitive Load: Worked examples before practice
|
|
- Adult Learning: Problem-based approach
|
|
|
|
**Part III: Mastery (Bloom's: Evaluate + Create)**
|
|
|
|
- Scaffolding: Independent challenges
|
|
- Cognitive Load: Integrate prior knowledge
|
|
- Adult Learning: Real-world projects
|
|
|
|
### Chapter-Level Application
|
|
|
|
1. **Introduction**: Activate prior knowledge (scaffolding), show relevance (adult learning)
|
|
2. **Concepts**: Manage cognitive load (chunking), start concrete (scaffolding)
|
|
3. **Tutorials**: Worked examples (cognitive load), problem-oriented (adult learning)
|
|
4. **Exercises**: Progress to independence (scaffolding), higher Bloom's levels
|
|
5. **Summary**: Reinforce learning, connect to next chapter
|
|
|
|
---
|
|
|
|
## Resources and Further Reading
|
|
|
|
- **Bloom's Taxonomy Revised**: Anderson & Krathwohl (2001)
|
|
- **Cognitive Load Theory**: Sweller, Ayres, & Kalyuga (2011)
|
|
- **Adult Learning Theory**: Knowles (1984)
|
|
- **Instructional Design**: Gagne's Nine Events of Instruction
|
|
- **Technical Writing**: Diátaxis framework (documentation.divio.com)
|