Further Reading and Resources

The principles of digestible interface design connect to a rich body of work in software engineering, cognitive psychology, and design thinking. This section provides resources for deeper exploration.

Related Chapters in This Book

Part 1: Foundations

Chapter 3: Architecture Principles - Component decomposition and interface boundaries
Chapter 5: New Bottlenecks - How interface complexity becomes a bottleneck at scale (coming soon)

Part 2: Playbook

Requirements to Design - Translating requirements into digestible interfaces (coming soon)
Design to Implementation - Breaking down design into implementable interfaces (coming soon)

Part 3: Patterns & Tools

Interface Boundaries - Deep dive into interface design patterns (coming soon)
OpenAPI for REST APIs - Designing digestible REST interfaces
JSON Schema Validation - Using schemas to make interfaces self-documenting (coming soon)

External Resources

Books

"The Design of Everyday Things" by Don Norman Classic work on interface design principles (physical and digital). The cognitive psychology applies equally to software interfaces.
"A Philosophy of Software Design" by John Ousterhout Directly addresses complexity management and interface design for software systems.
"Clean Code" by Robert C. Martin Chapters on function design and naming are particularly relevant to digestible interfaces.
"Domain-Driven Design" by Eric Evans Bounded contexts and ubiquitous language relate directly to digestibility.

Papers and Articles

"The Magical Number Seven, Plus or Minus Two" by George A. Miller (1956) Foundational paper on working memory limits.
"Cognitive Load Theory" by John Sweller Framework for understanding how complexity affects learning and comprehension.

Tools and Resources

Linters and Complexity Analyzers
- pylint, eslint (parameter count, complexity metrics)
- sonarqube (code smell detection)
- radon (Python complexity metrics)
API Design Guides
- Microsoft REST API Guidelines
- Google API Design Guide
- Stripe API Design Philosophy

Online Communities

/r/ExperiencedDevs on Reddit - Discussions on interface design tradeoffs
Software Engineering Stack Exchange - Q&A on API and interface design
Hacker News - Debates on software design philosophy

Continuing Your Learning

Practice makes principles stick. Here are exercises to build your digestible interface skills:

Exercise 1: Interface Audit

Pick a module in your current codebase and evaluate three interfaces using the metrics from Section 8:

Parameter count (target: ≤5)
Cyclomatic complexity (target: ≤10)
Lines per function (target: ≤50)
Nesting depth (target: ≤3)

Document your findings and identify one interface to refactor.

Exercise 2: Refactoring Practice

Take a function with more than 7 parameters and refactor it:

Group related parameters into data classes
Replace boolean parameters with enums or named methods
Make implicit dependencies explicit
Verify the refactored interface passes the "explain in 2-3 sentences" test

Exercise 3: AI Agent Test

Show an interface you've designed to an AI agent (Claude, GPT, etc.) without providing extensive documentation:

Give only the function signature and type definitions
Ask it to write code that uses the interface
Observe where it hesitates or makes mistakes
Use the findings to improve the interface

Exercise 4: Consistency Audit

Review a service layer in your codebase:

List all CRUD methods across different entities
Check for naming consistency (get vs fetch vs retrieve)
Check for return type consistency (nullable vs exceptions)
Document inconsistencies and propose a unified pattern

Exercise 5: Error Message Review

Intentionally misuse five interfaces in your codebase:

Call with wrong types
Call with invalid values
Omit required parameters

Rate each error message: Does it answer "What went wrong?", "Why?", and "How do I fix it?"

These exercises build intuition for digestible design. Over time, you'll find yourself naturally creating interfaces that are easy for both humans and AI agents to understand and use correctly.