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/book-structures.md

5.4 KiB
Raw Blame History

Publisher-Specific Book Structures

This document provides structure guidelines for major technical book publishers and frameworks.

PacktPub Standard Structure

Format: Hands-on, project-based learning

Typical Structure:

  • 10-15 chapters
  • 20-30 pages per chapter
  • 300-400 pages total

Chapter Pattern:

  1. Learning objectives (What you will learn)
  2. Introduction with real-world context
  3. Hands-on tutorials with code
  4. Best practices and tips
  5. Summary
  6. Further reading/resources

Key Characteristics:

  • Very practical, code-heavy
  • Step-by-step tutorials throughout
  • Clear learning outcomes per chapter
  • Real-world examples
  • Beginner to intermediate focus

O'Reilly Learning Path Structure

Format: Conceptual→Practical progression with depth

Typical Structure:

  • Part-based organization (3-5 parts)
  • 12-20 chapters across parts
  • Varying chapter lengths (15-40 pages)
  • 400-600 pages total

Part Pattern:

  • Part I: Foundations and core concepts
  • Part II: Intermediate techniques
  • Part III: Advanced topics
  • Part IV: Real-world applications (optional)

Chapter Pattern:

  1. Concept introduction
  2. Detailed explanation with diagrams
  3. Code examples and experiments
  4. Exercises for practice
  5. Summary and what's next

Key Characteristics:

  • Rich code examples with explanations
  • Sidebars for deep dives
  • Callouts for warnings/tips
  • Comprehensive index
  • Intermediate to advanced focus
  • Theory balanced with practice

Manning In-Depth Tutorial Structure

Format: Deep tutorial with progressive build approach

Typical Structure:

  • 12-15 chapters
  • 25-35 pages per chapter
  • 350-500 pages total

Chapter Pattern:

  1. Motivating example (real-world problem)
  2. Concept explanation (theory)
  3. Hands-on tutorial (implementation)
  4. Iterative improvements
  5. Real-world application
  6. Exercises throughout

Key Characteristics:

  • Start with working example, then explain
  • Progressive complexity (build up incrementally)
  • MEAP (Manning Early Access Program) format
  • Code listings are numbered and referenced
  • Exercises integrated into flow, not just at end
  • Intermediate to advanced focus

Diátaxis Framework (Publisher-Agnostic)

Four Documentation Types:

1. Tutorials (Learning-Oriented)

  • Take reader through series of steps
  • Help beginners get started
  • Minimal explanation, maximum doing
  • Reliable and repeatable

2. How-To Guides (Task-Oriented)

  • Show how to solve specific problem
  • Assume some knowledge
  • Series of steps to achieve goal
  • Practical and focused

3. Explanation (Understanding-Oriented)

  • Clarify and illuminate
  • Provide background and context
  • Make connections
  • Discuss alternatives and decisions

4. Reference (Information-Oriented)

  • Describe the machinery
  • Accurate and complete
  • Structure by API/function
  • Consistent format

Application to Technical Books:

  • Early chapters: Tutorials + some Explanation
  • Middle chapters: How-To Guides + Explanation
  • Later chapters: Advanced How-To + deeper Explanation
  • Appendices: Reference material

Chapter Micro-Structures

Introduction Section (1-2 pages)

  • Hook with real-world problem
  • Overview of chapter content
  • Prerequisites reminder
  • What readers will accomplish

Main Content Section (3-6 pages each)

  • Concept explanation
  • Code example with walkthrough
  • Common mistakes to avoid
  • Best practices

Exercises Section (2-3 pages)

  • Guided practice (3-4 exercises)
  • Challenge problems (1-2 harder)
  • Solutions or hints

Summary Section (1 page)

  • Key concepts recap
  • Skills checklist
  • Preview of next chapter
  • Additional resources

Self-Publishing Best Practices

Platforms: Leanpub, KDP, Gumroad

Flexibility: No strict structure requirements

Recommendations:

  • Follow general best practices from major publishers
  • Typical range: 200-500 pages
  • Clear table of contents
  • Consistent formatting
  • Professional editing
  • Code repository on GitHub
  • Regular updates possible (advantage of self-publishing)

Consider:

  • Audience expectations (what format do they expect?)
  • Competition (what structure do similar books use?)
  • Your teaching style (tutorial vs conceptual vs reference)
  • Maintenance burden (easier to update modular structure)

General Structure Guidelines

Front Matter:

  • Title page
  • Copyright
  • Table of contents
  • Preface/Introduction
  • About the author
  • About the reviewers (if applicable)
  • Prerequisites
  • How to use this book
  • Conventions used
  • Companion code repository

Main Content:

  • Organized into parts (optional) and chapters
  • Progressive difficulty
  • Consistent chapter structure
  • Cross-references between chapters

Back Matter:

  • Appendices (reference material)
  • Glossary
  • Index
  • Additional resources
  • Answer key (if solutions not inline)

Choosing the Right Structure

Choose PacktPub style for:

  • Beginner-focused content
  • Very practical, project-based books
  • Clear learning paths
  • Hands-on tutorials

Choose O'Reilly style for:

  • Intermediate to advanced content
  • Conceptual depth required
  • Multiple parts with different focus
  • Comprehensive reference value

Choose Manning style for:

  • Deep tutorial approach
  • Progressive build-up
  • Iterative improvement examples
  • Strong narrative flow

Choose Diátaxis framework for:

  • Documentation-style books
  • Multiple content types needed
  • Clear separation of concerns
  • Reference-heavy content