ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-technical-writing/data/learning-frameworks.md

10 KiB
Raw Blame History

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)