Managing Complexity to Avoid Burnout

Complexity is fundamentally about state space: the number of possible states a system can occupy. Fewer states mean less complexity. An integer between 1 and 10 is manageable because it has only ten possible values. In contrast, a floating-point number can take on nearly infinite values, expanding the state space dramatically. The trick is to reduce this state space—limiting possibilities—to minimize mental effort. How to Reduce Complexity The key is restriction: always aim to narrow the state space wherever possible. • Be Explicit: Clarity reduces complexity by making choices unambiguous. Whether you’re designing interfaces, defining options, or issuing instructions, explicitness constrains the range of possibilities. • For example, instead of leaving requirements open-ended, provide clear directions and well-defined constraints for the task at hand. • In any team—whether you’re a platform engineer, developer, or team lead—explicit instructions and defined options ensure everyone operates from the same reduced state space. Providing Context: Where and How A tightly constrained context minimizes the mental energy needed to understand a task. Consider the difference between a project’s README file and a generic Confluence document: the README anchors instructions directly to the project, while a broader document can leave too much to interpretation. Visual aids also reduce complexity by making context explicit. A photo or video might show a Docker container in action or highlight the correct environment variables, saving words and potential misunderstandings. Yet, nothing beats running code. A working example cuts out ambiguity completely—it’s much easier to modify a proven example than to interpret a vague description. Examples of Reducing Complexity Terraform Variables: Better vs. Worse Cardinality # Worse: Unconstrained variable with high cardinality variable "instance_type" { type = string description = "EC2 instance type to use" default = "" } # Better: Constrained variable with limited options variable "instance_type" { type = string description = "EC2 instance type to use" validation { condition = contains(["t2.micro", "t3.micro", "t3a.micro"], var.instance_type) error_message = "Must be one of t2.micro, t3.micro, or t3a.micro" } default = "t2.micro" } In the first example, the free-form string creates an enormous and ambiguous state space. In the second, constraining the options significantly reduces potential errors. Removing Dead Code Cleaning up your codebase is like pruning a tree—it removes unnecessary branches so the healthy parts can flourish. Removing dead code alleviates the mental burden of navigating outdated or irrelevant paths, allowing developers to focus on what truly matters. Imagine a legacy service cluttered with inactive endpoints and unused functions. Removing this dead code streamlines the codebase, making the active paths clear and reducing the overall state space. Configuration as Code Treating configuration as code means that every change is tracked explicitly, thereby reducing ambiguity. Each configuration file "locks in" a set of possibilities, leading to more predictable behavior. Configuring things as code is essential not only for managing complexity but also for serving as self-documenting code. By encoding all necessary settings explicitly, configuration as code provides much clearer instructions than vague verbal directives. Example: Clear vs. Vague Setup Instructions • Bad Example: "Set up the dev environment." — Too vague; it leaves too many possibilities. • Good Example: "Set up dev environment by running docker compose up. Refer to the .env.example for the environment variables you need to set, with comments detailing where to obtain any secret values." — By encoding all necessary configurations in a docker-compose.yml file and detailing required environment variables in a .env.example file, the state space is significantly constrained. When configuration isn’t defined as code, developers face a sprawling, undefined state space that makes it difficult to determine what is truly needed. In contrast, configuration as code provides a clear, reproducible setup that minimizes uncertainty, reduces potential issues, and ultimately prevents confusion by offering clear, concrete instructions. How Effective Communication Can Aid in Managing Complexity Managing complexity isn’t solely the responsibility of managers—it’s about clear communication across all levels of a team. Regardless of your role, effective communication constrains the state space by ensuring everyone shares the same context and expectations. Consider a scenario where project details are scattered or vague. Instead of diving into an enormous, undefined state space, engage in shared communication to narrow the possibilities. Whether in one-on-one conver

Feb 24, 2025 - 16:47

Complexity is fundamentally about state space: the number of possible states a system can occupy. Fewer states mean less complexity. An integer between 1 and 10 is manageable because it has only ten possible values. In contrast, a floating-point number can take on nearly infinite values, expanding the state space dramatically. The trick is to reduce this state space—limiting possibilities—to minimize mental effort.

How to Reduce Complexity

The key is restriction: always aim to narrow the state space wherever possible.

• Be Explicit: Clarity reduces complexity by making choices unambiguous. Whether you’re designing interfaces, defining options, or issuing instructions, explicitness constrains the range of possibilities.

• For example, instead of leaving requirements open-ended, provide clear directions and well-defined constraints for the task at hand.

• In any team—whether you’re a platform engineer, developer, or team lead—explicit instructions and defined options ensure everyone operates from the same reduced state space.

Providing Context: Where and How

A tightly constrained context minimizes the mental energy needed to understand a task. Consider the difference between a project’s README file and a generic Confluence document: the README anchors instructions directly to the project, while a broader document can leave too much to interpretation.

Visual aids also reduce complexity by making context explicit. A photo or video might show a Docker container in action or highlight the correct environment variables, saving words and potential misunderstandings. Yet, nothing beats running code. A working example cuts out ambiguity completely—it’s much easier to modify a proven example than to interpret a vague description.

Examples of Reducing Complexity

Terraform Variables: Better vs. Worse Cardinality

# Worse: Unconstrained variable with high cardinality
variable "instance_type" {
  type        = string
  description = "EC2 instance type to use"
  default     = ""
}

# Better: Constrained variable with limited options
variable "instance_type" {
  type        = string
  description = "EC2 instance type to use"
  validation {
    condition     = contains(["t2.micro", "t3.micro", "t3a.micro"], var.instance_type)
    error_message = "Must be one of t2.micro, t3.micro, or t3a.micro"
  }
  default = "t2.micro"
}

In the first example, the free-form string creates an enormous and ambiguous state space. In the second, constraining the options significantly reduces potential errors.

Removing Dead Code

Cleaning up your codebase is like pruning a tree—it removes unnecessary branches so the healthy parts can flourish. Removing dead code alleviates the mental burden of navigating outdated or irrelevant paths, allowing developers to focus on what truly matters.

Imagine a legacy service cluttered with inactive endpoints and unused functions. Removing this dead code streamlines the codebase, making the active paths clear and reducing the overall state space.

Configuration as Code

Treating configuration as code means that every change is tracked explicitly, thereby reducing ambiguity. Each configuration file "locks in" a set of possibilities, leading to more predictable behavior.

Configuring things as code is essential not only for managing complexity but also for serving as self-documenting code. By encoding all necessary settings explicitly, configuration as code provides much clearer instructions than vague verbal directives.

Example: Clear vs. Vague Setup Instructions

• Bad Example: "Set up the dev environment."

— Too vague; it leaves too many possibilities.

• Good Example: "Set up dev environment by running docker compose up. Refer to the .env.example for the environment variables you need to set, with comments detailing where to obtain any secret values."

— By encoding all necessary configurations in a docker-compose.yml file and detailing required environment variables in a .env.example file, the state space is significantly constrained.

When configuration isn’t defined as code, developers face a sprawling, undefined state space that makes it difficult to determine what is truly needed. In contrast, configuration as code provides a clear, reproducible setup that minimizes uncertainty, reduces potential issues, and ultimately prevents confusion by offering clear, concrete instructions.

How Effective Communication Can Aid in Managing Complexity

Managing complexity isn’t solely the responsibility of managers—it’s about clear communication across all levels of a team. Regardless of your role, effective communication constrains the state space by ensuring everyone shares the same context and expectations.

Consider a scenario where project details are scattered or vague. Instead of diving into an enormous, undefined state space, engage in shared communication to narrow the possibilities. Whether in one-on-one conversations or team chats, clarifying questions and explicit answers build a collective “truth map” that everyone can rely on.

Constraining State Space for Yourself

Not everyone has the luxury of neatly scoped tasks. Often, you must navigate vast, unconstrained state spaces. The best way to tackle this is to ask questions early and often—preferably in a shared communication channel.

Each question posed, and each answer received, narrows down the range of possibilities. This shared "truth map" prevents isolated, incomplete interpretations and ensures a common understanding across the team.

After the conversation, gather the facts by diving into the codebase. Experiment with isolated examples to verify assumptions. Running code not only confirms the current state but also anchors your understanding in concrete reality.

Key Takeaways

• Engage in Shared Communication: Use collaborative channels to build a common understanding, thereby reducing complexity.

• Gather Facts Actively: Verify assumptions by exploring the codebase and running small examples.

• Constrain Through Experimentation: Concrete, working examples replace vague instructions with clear, executable guidance.

By reducing the state space—whether through explicit instructions, shared communication, or runnable code—you conserve mental energy and create an environment that is both efficient and less prone to burnout.