Tony Alicea

Trace: Declarative Modeling for the AI Age

2026-03-03T00:00:00Z

Trace: Declarative Modeling for the AI Age

Spec first, then plan, then code. In the age of AI, most developers already understand the value of this when working with an AI agent.

What changes when an LLM is generating the code is the weight placed on how the spec is written. It's no longer just communication between people who can ask each other questions, it's the primary input to a system that will produce significant amounts of code. Vague specs produce vague implementations, and the gap between what you wrote and what you meant shows up quickly in the generated output.

Trace is a standard for writing that spec: specifically, writing it in a declarative, structured way that an LLM can act on and that a developer can learn from.

That second part matters as much as the first. The challenge for developers learning to code today is that the most accessible entry point to the craft, writing syntax, can now be largely delegated to a language model. That shifts attention toward the harder and less visible work: understanding what a system actually is before anyone writes a line of it. What are the boundaries between parts of the system? Who owns what data? What rules govern how things change? How do separate areas of the software communicate without becoming one tangled dependency?

These are questions of systems thinking, and they're not easy to develop in the abstract. Trace is designed to help with this. Defining a domain forces you to answer what it owns and what it doesn't. Writing a glossary forces precision about words that teams often treat as interchangeable until they discover mid-build that they meant different things. Writing access rules for a persona forces you to think about a real person's relationship to data, not just which buttons they can see on a screen.

The structure won't let you skip past these questions, and working through them carefully is itself an education in how systems are built and practice to build architectural skill.

In this post we'll walk through each part of a Trace a running example, a small clinic system with patients, providers, and a front desk staff who keeps everything moving.

The 'L' in LLMs

The first L in LLM stands for "Large." But the more interesting letter, for our purposes, is the second one: Language.

Traditional specifications were designed for parsers. They used formal grammars, rigid syntax, and machine-readable structures that are highly proscriptive.

Because LLMs process natural language, that proscriptive need largely disappears. A specification written in clear, structured prose can be understood by AI and human alike.

This doesn't mean writing a vague paragraph and calling it a spec. Trace is designed around organizational consistency, not syntactic rigidity. The LLM doesn't need formal grammar; it needs structure. A consistent structure tells it what the access rules are, what the events are, what the business rules are. Natural language inside that structure conveys intent and meaning. The spec is readable by design, and actionable because of its organization.

A Trace Is A Folder

A Trace is a standardized folder structure. Our example, while in progress, might look like this:

fish-family-medicine/
├── overview.md
├── stack.md
├── personas/
│   ├── patient.persona.md
│   ├── front-desk.persona.md
│   └── provider.persona.md
├── domains/
│   ├── scheduling.domain.md
│   ├── clinical.domain.md
│   └── billing.domain.md
└── flows/
    ├── book-appointment.flow.md
    ├── front-desk-dashboard.flow.md
    └── patient-check-in.flow.md

Overview

The overview.md file gives an overview of the system being built, and provides a place for a global glossary of terms used by the underlying business the software is supporting.

GLOSSARY:
- Patient: A person receiving care at the practice.
- Provider: A doctor, NP, or PA who sees patients.
- Appointment: A scheduled time slot. Not the same as a visit.
- Visit: A clinical encounter that happens when a patient checks in. Not the same as an appointment.
- Claim: A billing request submitted to insurance after a visit is completed.
- Front Desk: Administrative staff who manage the schedule and patient flow.
- Check-In: The moment a patient arrives and is marked present. Bridges Scheduling and Clinical.

Stack

Before describing behavior, Trace captures the technical decisions that affect everything else. These live at the root in a stack.md file.

BACKEND:
- Runtime: Node.js (LTS)
- Framework: Fastify
- Language: TypeScript

DATA:
- Database: Supabase (Postgres)
- ORM: Drizzle

FRONTEND:
- Framework: React + Vite
- State: Zustand
- Styling: Tailwind CSS

These decisions live in one place so an LLM generating code never has to guess the runtime, the ORM, or the state management library. Stack also includes a SYSTEM DEFAULTS section for cross-cutting decisions like ID strategy, audit fields, and how money is stored: things that affect every entity and every domain in the system.

Design System Forward

Stack also includes the design system reference: where component libraries, design tokens, style guides, or design files live. This connects every flow in the spec to the visual language of the product, so the LLM knows what UI building blocks are available and which to use.

The design system isn't a separate concern from the architecture; it's part of the same document.

Domains

Domains (./domains/*.domain.md) are the heart of a Trace. Each domain is a self-contained area of the system with its own vocabulary, rules, and data. They communicate with each other through events, not by reaching directly into each other's data.

The first question to ask when defining a domain is: Is this one thing, or secretly two things?

Fish Family Medicine is a good example. You might be tempted to create an "Appointment" domain and move on. But look more carefully. An Appointment is a scheduled time slot. A Visit is what actually happens when the patient walks through the door. They're related, but they're not truly the same conceptual entity.

You could simply state that a Visit is scheduled and occurs or does not. That may work fine. But as business rules grow, and user research shows the reality of appointments versus visits, thinking through these domains may save untangling later.

Glossary

There is a global glossary for terms that always have the same meaning. However you will find in many organizations that the same word means different things to different groups.

Domains document the terms that matter in their context. Whether terms unique to a domain or that differ from the general global meaning.

GLOSSARY:
- No-Show: A patient who had a confirmed appointment but never checked in.

Whether from the global glossary or domain-specific, when the LLM reads a rule about an "Appointment," it knows exactly what that word means in this context, not some general notion in its training data of what an appointment could be.

Constraints

Constraints define what a domain can and cannot do, and how it relates to the rest of the system.

CONSTRAINTS:
- Scheduling owns appointment lifecycle only. It does not know about clinical notes,
  diagnoses, or billing.
- "Appointment" in this context is a time slot. It is NOT a visit.
- When a patient checks in, Scheduling emits an event. What happens clinically after
  that is not Scheduling's concern.
- Never include reason_for_visit in SMS messages (PHI constraint).

This is the domain's boundary. Constraints protect the architecture from drift. When an LLM implements Scheduling, it knows not to reach across into Clinical. The boundary is explicit in the spec, not just implied by convention.

Entities

Entities are the data the domain owns. They're defined at the least with the fields that actually matter, though they can be exhaustive.

# ENTITY: Appointment
MUST HAVE:
- id: UUID
- status: Enum (Requested, Confirmed, CheckedIn, Cancelled, NoShow)
- appointment_time: DateTime
- duration_minutes: Integer
- reason_for_visit: Text
- patient_id: UUID
- provider_id: UUID

The MUST HAVE pattern keeps the spec honest. These aren't optional fields; they're the fields without which the entity doesn't make sense. The LLM generates the full schema from this, applying the Stack defaults along the way.

Events

Domains communicate outward by publishing events. Other domains listen and react.

# EVENT: PatientCheckedIn
TRIGGER:
- When Appointment.status changes to CheckedIn.

PAYLOAD:
- appointment_id
- patient_id
- provider_id
- reason_for_visit

# EVENT: AppointmentConfirmed
TRIGGER:
- When Appointment.status changes to Confirmed.
- Send a confirmation text via Twilio SMS with the appointment date, time, and provider name.

PAYLOAD:
- appointment_id
- patient_id
- appointment_time
- provider_name

The Clinical domain, for example, declares exactly how it reacts to PatientCheckedIn:

# LISTENS TO: PatientCheckedIn (from Scheduling domain)
- Creates a new Visit in InProgress status.
- Sets Visit.patient_id, provider_id, and appointment_id from the event payload.
- Sets Visit.chief_complaint from the event's reason_for_visit.

Neither domain needs to know how the other works internally; they only need to know the events being published and what to do when they arrive. The system stays decoupled at the architecture level, not just in the implementation.

The LISTENS TO keyword is a simple way to describe what events domains depend on.

How events actually work in code is an implementation question. Domains communicate via events architecturally and conceptually. Developers can work with the intended stack and the generated plan to determine what a concrete implementation looks like.

Rules

Rules are the business logic that must be enforced, written in plain language and labeled for reference.

RULES:
- R1: Status moves forward only: Requested -> Confirmed -> CheckedIn. Cancelled and
  NoShow can happen from Requested or Confirmed.
- R2: A provider cannot have overlapping appointments.
- R3: A new patient appointment must be at least 30 minutes. Returning patient
  appointments can be 15 minutes.
- R4: Appointments cannot be scheduled more than 6 months in advance.

The labels are useful. "This test covers R3" is useful in a code review. "This test covers the appointment length rule" is ambiguous. When a stakeholder changes their mind about R2, you can find every place it's referenced in code (I find the LLM tends to put them in comments where they are implemented), in tests, and in tickets.

Stubs

Some rules are real but require their own implementation planning. They're complex enough that dropping them into a domain spec would derail the conversation.

RULES:
- R5 STUB: Cancellations less than 24 hours before appointment time incur a
  cancellation fee.

The STUB modifier signals that this rule exists and that the signature should be enforced, but the implementation will be planned separately. This allows developers to choose when to drop deeper into the implementation and work a problem more carefully.

Externals

In modern applications it's common for a domain to integrate with something outside the system. With scheduling, for example, that might be something like Twilio SMS for appointment confirmations.

EXTERNAL: Twilio SMS

# LISTENS TO: Twilio SMS
- When a patient replies CANCEL, find the matching appointment by patient phone number
  and cancel it. Appointment.R1 and Appointment.R5 still apply.

The list of externals is declared simply domain file. The LISTENS TO section describes how the domain reacts to inbound messages from it.

Personas

A persona (./personas/*.persona.md) in Trace represents real people with constraints, goals, and frustrations, and with explicit data access rules.

# PERSONA: Patient

DESCRIPTION:
- A person receiving care at the practice.
- Wide age range. Many are not tech-savvy.
- Cares about getting an appointment quickly and not being surprised by bills.
- Often anxious when visiting the doctor. Clarity reduces anxiety.

That last line isn't decoration. It shapes how flows are designed for this persona: confirm steps clearly, reduce ambiguity, never leave patients wondering what happens next. That's a design principle, and it lives in the spec where it can actually influence the work.

Access

Access rules define what data each persona can see and modify. These rules are enforced at the data layer, not just in the UI.

ACCESS:
- Can only see their own appointments and visit history.
- Can see their provider's name and specialty. Cannot see other patients' data.
- Can cancel or reschedule their own appointments.
- Cannot see clinical notes until the provider releases them.

It's not enough to hide a button in the interface. The spec says what data each persona is allowed to touch at the system boundary. That drives API permissions, middleware, and database row-level security.

User Research

Trace treats user research as a first-class citizen of the specification. If you've done interviews or gathered insights about how real people use your system, they belong here, not in a separate document that gets lost six months into the project.

## Research Findings

### From user interviews
- 4 of 6 patients said they've accidentally booked the wrong appointment type because
  the options were confusing.
- Patients over 60 strongly preferred calling over using an app but were open to
  "something simple."
- Multiple patients mentioned frustration with not knowing if their insurance was
  verified before arriving.

### Jobs to Be Done
- When I need to see my doctor, I want to book the right type of appointment without
  having to know medical terminology.
- After my visit, I want to understand what I owe before I get a surprise bill.

When an LLM generates flows for the Patient persona, this context shapes the output. Plain language over medical categories. Insurance status visible at check-in. The research doesn't stay in a slide deck; it travels with the spec into the implementation.

Flows

Flows describe how each persona moves through the system. They're the bridge between the domain model and the actual user experience.

Flows in Trace have two strategies.

normalize spreads the workflow across multiple screens, each with its own URL. This works well for processes that benefit from one-thing-at-a-time focus, like a patient booking an appointment for the first time.

denormalize keeps the workflow on a single screen with changing frame states, where the URL doesn't change. This works well for practiced users who need everything in front of them, like a front desk coordinator managing a full day's schedule.

If you want to read more about the thinking behind normalization and denormalization as a UX principle, I wrote a full book on it which is free to read online.

Domains

Each flow declares its strategy, persona, and the domains it touches in YAML frontmatter. This makes dependencies explicit and helps determine implementation order.

---
flow: BookAppointment
strategy: normalize
persona: Patient
domains:
  - Scheduling
---

Screens, Frames, and Normal UI

Flows in Trace are built around the Normal UI usability concept, but it's really just user flows with some specific additional ideas.

You pick normalize or denormalize for each flow, and the structure follows from that choice. In a normalized flow, Screens are the primary unit, each a distinct URL route. In a denormalized flow, there's one Screen containing multiple Frames, which are the states the user transitions between without navigating away.

This explicity documented choice, beyond a prototype or design system component, serves as a reminder of why a flow is designed a certain way, based on what we know about how users will work.

Book Appointment is normalized because booking is a first-time or infrequent task for a patient. One decision per screen, clear progress, no risk of accidentally skipping something important:

---
flow: BookAppointment
strategy: normalize
persona: Patient
domains:
  - Scheduling
---

## SCREEN: Choose Reason
- REF: design-system/templates/card-selection-grid.jsx
- DATA: A simplified list of reasons (e.g., "Routine Checkup", "I'm Feeling Sick",
  "Follow-up Visit", "Something Else").
- These map to internal reason_for_visit values but are displayed in plain language.
- ACTION: Select any standard reason -> Goes to SCREEN: Choose Provider
- ACTION: Select "Something Else" -> Goes to SCREEN: Describe Concern

## SCREEN: Choose Provider
- REF: design-system/templates/list-selection.jsx
- REF: design-system/mockups/provider-card-layout.png
- DATA: Provider.name, Provider.specialty, Provider.accepting_new_patients
- Only show providers relevant to the selected reason.
- ACTION: Select a provider -> Goes to SCREEN: Choose Time

The Front Desk Dashboard is denormalized because front desk staff are practiced users managing a high-volume day. They need to act quickly without losing context of the full schedule:

---
flow: FrontDeskDashboard
strategy: denormalize
persona: FrontDesk
domains:
  - Scheduling
---

# SCREEN: Today's Schedule
> GOAL: See everything at a glance. Manage the day's flow without navigating away.

## FRAME: Schedule View
- REF: design-system/templates/data-table-with-status.jsx
- SOURCE: Appointment entity (filtered by date == today, ordered by appointment_time)
- ACTION: Click appointment -> Transitions to FRAME: AppointmentDetail

## FRAME: AppointmentDetail
- ENTERS_FROM: FRAME: Schedule View
- DATA:
  - Appointment.status
  - Appointment.appointment_time
  - Patient.name
  - Patient.insurance_status
- ACTION: "Check In" -> Changes Appointment.status to CheckedIn, Transitions to
  FRAME: Schedule View. Only available if status is Confirmed.
- ACTION: "Back" -> Transitions to FRAME: Schedule View

The LLM knows the route, the state within it, what data to display, and what happens when the user acts. The strategy, normalize or denormalize, determines the structure, and the spec makes that decision explicit rather than leaving it to whoever builds the screen.

Design System References

Flows reference design system assets directly: component names, or image mockups from a design file.

## SCREEN: Choose Provider
- REF: design-system/templates/list-selection.jsx
- REF: design-system/mockups/provider-card-layout.png

This connects the architecture directly to the UX design. The LLM uses these references. Human readers know where to look. The design files are part of the same conversation as the spec.

Generating Plans

Once a Trace is written, you can generate an implementation plan from it.

For larger software, an effective approach is vertical slices, implementing one complete feature at a time from database to UI, so that each slice is actually usable when it's done. Alternatively, plans can be organized by flow, where each flow references its needed domains and the plan builds them out in the order the flows require.

A plan generated from Fish Family Medicine might look like this:

Phase 1: Scheduling Core
  - Appointment entity and migrations
  - Confirm, cancel, no-show endpoints
  - PatientCheckedIn and AppointmentConfirmed events

Phase 2: Patient Booking Flow
  - Book Appointment screens
  - Patient access rules

Phase 3: Front Desk Dashboard
  - Today's Schedule screen and frame states
  - Check-in action

Phase 4: Clinical Integration
  - Visit entity created on PatientCheckedIn
  - Provider view of today's visits

Phase 5: Billing Integration
  - Claim created when VisitCompleted fires

Each phase can be implemented by an agent or agent swarm with a human-in-the-loop working within clear boundaries. The Trace defines what each phase needs to know. The plan says what order to build it in.

Agent swarms can implement multiple phases in parallel when domain dependencies allow it. Phases 2 and 3 can proceed simultaneously because they touch the same Scheduling domain from different directions. The spec makes those relationships visible, so the plan reflects them accurately.

The Full Spec

The complete Trace specification, including all file formats, keywords, and examples, is on GitHub:

https://github.com/anthonypalicea/trace

The Agent Skill

The spec includes an agent skill you can use directly. The skill has two modes.

Author Mode is for designing a new system from scratch. The skill guides you through the process: What does the system do? Who uses it? What are the core domains? It asks questions, helps you make decisions, and produces a complete Trace at the end. At the close of every session, it calls out open questions, the gaps in the architecture that need answers before implementation can begin.

If a newer developer is using the skill, it includes educational notes as-you-go.

Implement Mode is for building from an existing Trace. The skill reads the spec, builds an implementation plan, gets your approval, and then builds phase by phase with review gates between each phase.

At the end of planning the LLM is asked to present you with open questions, to help find gaps in the architecture. Fill in those gaps and proceed with code generation.

The skill is at the same GitHub link:

https://github.com/anthonypalicea/trace

Clone the repo, read the spec, try out the Agent Skill. Try building a Trace (or use the example), generating a plan, and letting an LLM do some implementation.

I've found it works quite well!

Keeping Specs In Sync

Inevitably some change will occur after coding has begun. Have the LLM help you keep the Trace up-to-date when necessary.

I like to think of the spec as the source of truth that everyone can reference.

The Next Generation of Developers

For you developers who are earlier in your careers: the rise of AI code generation is sometimes framed as a threat. The argument goes, if a machine can write the code, there's less for developers to do, syntax knowledge matters less, and the path into software is narrowing. I think that's wrong.

What AI changes is where the intellectual work focuses. Understanding a problem well enough to describe it clearly. Designing a system that respects the people who use it. That work becomes more valuable as a result of AI, because it's the work that AI can't do for you.

Trace is, in part, a tool for that work. It gives developers a framework for thinking clearly about systems before writing a line of code. The domains, the rules, the personas, the access controls are all visible, reviewable, and improvable before anything gets built. That's good engineering with or without AI in the picture, and it's something worth learning deliberately.

If you're learning software development right now, learn to think in systems. Learn to ask why a rule exists. Learn to think about when pieces of a system need to communicate and what needs to be communicated. Learn to understand the people who will use what you build. Learn to think clearly about what a system is before you worry about how it works. Those skills travel with you regardless of what the tools look like five years from now.

That's what Trace is for.

The spec is open source. Please use it, adapt it, and share it. I hope it helps you build something better and helps new developers begin to find their footing.

The Future of Self-Paced Online Education

2026-02-24T00:00:00Z

The Future of Self-Paced Online Education

A lot of words have been dedicated to how LLMs are changing the landscape of software development. But there's another arena that has been massively impacted by the rise of AI and deserves more discussion: the self-paced online education industry.

Thousands upon thousands of developers are self-taught, and that education, for many, included self-paced video courses. The student appetite for inexpensive (compared to universities) video course education powered the success of marketplaces and platforms like Udemy, Coursera, Teachable and more.

However, the past few years have seen a massive disruption of that success. This AI disruption is leaving the industry and learners with some open vital questions: What is the value of a video course when you seemingly can ask an interactive LLM to teach you anything? Are LLMs the right answer to a good education for developers? What will the next generation of self-paced learning look like?

Bona Fides

I've been a developer educator building self-paced video courses for over a decade. I released my first web development course on Udemy in late 2014.

Leading up to that, I found nearly all video courses, even popular ones, to be nothing but "follow along with me while I code"-style videos, which did not provide the mental models and understanding necessary to debug well and support a long career. I wanted to provide web development education for self-taught devs that was rooted in first-principles and computer science (I got a comp sci degree 25 years ago).

The results shocked me. To date I have over 370,000 enrolled students across Teachable, Udemy, and Pluralsight and I've heard from many students that my most well-known course, JavaScript: Understanding the Weird Parts, was the foundation of their career.

Over the years interacting with so many students, I've seen the challenges they face, the curricula that work, and what doesn't. Like many other instructors, I rode the wave of interest in inexpensive education, enjoyed watching students from all backgrounds and economic circumstances succeed, and was able to support myself and my family doing it.

Then, in 2024, something changed.

AI and Probabilistic Learning

The one true bottleneck of self-paced education was always the speed of getting student questions answered. There were lots of solutions like hiring teaching assistants, building online communities for student interaction, and more.

Enter AI. When ChatGPT output quality caused it to cement into the culture around 2023, AI chat bots began to provide something no self-paced instructor could hope to match: instant education gratification.

An LLM is a tireless instructor. It answers any question, expounds on any point, and never becomes frustrated with a student. By all appearances you can learn anything with an LLM.

The reality, of course, is more nuanced. LLMs are enormously sophisticated probabilistic word-guessing machines. Their underlying architecture is oriented, not around being correct (they have no real sense of 'truth'), but of outputting something that looks like the languages they were trained on.

In other words, if an LLM is inaccurate it's accomplished the core purpose of its design as long as the output reads like a human-written lie. That's not a small accomplishment. It's massively impacted the digital industry. But it isn't reliable learning.

Some will argue that human teachers make mistakes as well. That's certainly true. But there are two major differences between a human and an LLM in the area of mistakes:

A human teacher can learn from their mistakes.
It's far easier for the way you ask a question to nudge an LLM towards an erroneous response than it is when asking a human teacher.

LLMs also output confident-sounding text. In 2024, I began getting responses from students that challenged something I said in a lecture, and these responses would start with "ChatGPT said...".

Unsurprisingly, their LLM-based pushback was always incorrect, and often had to do with how they asked the question. They didn't have the knowledge yet to ask a question designed to get a good LLM response. But they trusted LLM output.

Thus we're faced with a kind of cognitive dissonance. LLMs can make fantastic educational partners. LLMs are also unreliable educational partners, encumbered by the knowledge (or lack thereof) of the one asking the question, and a poor education is a poor foundation for a career.

The Pivot

Instructors teaching "watch me code and parrot what I do" courses were especially vulnerable to the AI disruption.

But all instructors were vulnerable to the student assumption that AI could either teach them or do the work for them.

Many instructors have pivoted. Some to Developer Relations. Others to live teaching.

Live teaching is fantastic, and I've done it for years. However it is also more expensive for the student, and not scalable.

For myself, while I continued to enjoy creating courses for my own platform, Udemy, and Pluralsight, I wondered how to pivot affordable self-paced education in the age of AI. Learning companies and platforms were asking the same thing.

AI and Learning Innovation

Like most businesses, learning companies responded with attempts to include "AI innovation" in their service offerings. The aforementioned tools to build quizzes and content automated away some tasks for instructors, and you could feed transcripts of videos to an LLM so students could ask questions of it.

Udemy piloted one of the more interesting approaches, called "Role Play", where students could converse with an LLM avatar. Of course, this was still a chatbot and a prompt, wrapped in an engaging user experience. I found students loved Role Play, even as they commented that the AI was limited in the realism of its interactivity.

But that love of interactivity, coupled with the careful prompts that I wrote for Role Plays, began to spark some theories on what self-paced education innovation could really look like in the age of AI.

My next experiment was adding prompt-based AI exercises. In my course on semantic HTML and modern CSS, I teach students HTML first before opening a browser window. This way they learn to think semantically, and not get distracted or derailed by visual intent.

If you work in a front-end development team that cares about and is skilled in accessibility, then you might have a conversation about your semantic HTML choices. What's interesting about that is there are cases where there is no strictly correct answer. Multiple HTML elements may be arguably viable to markup a particular bit of the web document. I've had my share of fun conversations in that arena.

So, I gave my students a series of "AI-powered exercises" that were BYOLLM (Bring Your Own LLM). They pasted a prompt into their LLM, and had a conversation where they had to defend their semantic choice for a particular markup challenge. The LLM was instructed to not just accept their first answer, push back even if it was reasonable, and move on when they made a defense grounded in semantics.

It took testing and iteration, but I got a set of prompts that worked well across models. I also instructed the LLM to summarize the experience of the student at the end, and the student pasted that summary as homework into their learning app. In reviewing those responses I discovered what an interesting experience it was for students, and the results reflected in the reviews I got as well.

To discuss this further, let's coin some acronyms. If video courses are a form of human-led instruction (HLI), then these exercises were a form of AI-led instruction (ALI). But they were ALI with carefully curated and tested context. This is necessary because AI-led instruction, due to an LLM's tendency to drift in the direction the human gives it, is fundamentally flawed without knowledgeable instructor support.

For me this began to form some ground rules for a good AI-led instruction:

Context and prompts must be well-tested across models.
Curriculum needs to provide structured guidance but that is designed to survive non-determinism and student input.
An LLM must be given a personality and teaching approach that matches the intent of the instruction.
LLMs must be provided examples of inputs and outputs of the intended educational experience.

These concepts have provided a foundation for my experimentation with ALI, and still do. However, options to provide an even better student experience were on the horizon.

Skills, MCP, and the LLM Infrastructure

The eternal challenge of LLMs is their inherent probabilistic nature. Encouraging them to produce structured, accurate results is as much art and authoring as engineering.

The industry has provided standards to help. These same standards form the building blocks of AI-led curricula.

Agent Skills

The Agent Skills standard provides a way to give an LLM context and tools that it loads on-demand, saving context window space and reducing context rot.

The Model Context Protocol (MCP)

The Model Context Protocol provides a standardized way to expose data, tools, and workflows to an LLM from an external system.

MCP Apps

The MCP Apps standard is the real game changer for AI-led instruction.

MCP Apps allows an MCP server to return interactive UI applications as part of the LLM conversation.

This means you can return deterministic slices of interactivity interlaced with the LLM's non-deterministic inference.

WebMCP

The WebMCP standard allows web application functionality to be exposed as "tools" to an AI agent.

Essentially, the web page becomes an MCP server. This enables user and agent collaboration on the same web page.

The Infrastructure

These four standards form an infrastructure for enabling an AI agent to enhance the context of an LLM.

I think organizations and instructors that want to train in the age of AI need to be familiar with these standards, and how to build and use them. Because they also form the infrastructure for a high-quality student experience.

Learning Surfaces: An LLM-Based Future

We need a name for the combination of Agent Skills and MCP servers with resources curated by an instructor, with videos, interactive widgets, slides delivered via the MCP Apps standard. We need a name for the experience and the structure of these various elements presented via an LLM for educational purposes.

I call this combination a Learning Surface. Learning Surfaces are a form of AI-led instruction.

Self-paced AI-led instruction is unique because the learning experience will not be entirely reproducible like a video course is. Students may dive deeper on one topic than another. They may ask more of the LLM than the instructor intended. They may jump ahead, though the structure of the experience should discourage it.

Thus, while you might still call what you experience a "course", I think the curriculum that you build is more like the surface of a digital ocean. The student moves across the surface, likely in a pre-determined path. However the depth of exploration, the eddies of knowledge, are unique to that student's experience.

The flow of a Learning Surface for a coding course might look like this:

Student
   ↑↓
AI Agent
   ↑↓
Learning Surface
   ├── Skill context
   ├── MCP tools
   ├── UI Apps
   ├── Videos
   └── Code workspace

An enjoyable Learning Surface provides both required and optional material, making a course not only personalized, but an experience that supports repetition.

Skill and MCP Learning

Agent Skills and MCP provide context. Context nudges the LLM in the right direction.

A learning experience should start with a Skill. The student can install it into the AI agent of their choice. It provides things like voice, style, workflow, core context, and more.

You might have a Skill for a single course module, an entire course, or an entire school.

The Skill can help guide the usage of the MCP server. The server provides in-depth context (especially if paywalled, otherwise it may be in the Skill), deterministic tools needed during instruction, video snippets, interactive slides, and more.

MCP Apps can also provide context to the LLM. For example, the results of a student's interaction with a piece of UI. Thus the deterministic elements can feed forward into the non-deterministic LLM keeping it on track and in the flow of the student's moment-to-moment experience.

IDE Integration

For coding education, MCP Apps combined with IDEs make for a fantastic experience. Students clone a course repo. The student can watch a video and interact with a widget in an agent integrated into the IDE, and the agent can read the code the student types, allowing the LLM to provide feedback.

This is a broad space to provide in-depth training in a real-world work environment.

WebMCP Learning Experiences

WebMCP really opens the doors to innovate on AI-led experiences.

Designing a web application with two intended users: the student and their agent with whom they are collaborating, coupled with the other foundational pieces of infrastructure we've discussed, really means the limits are open to instructor imagination.

I believe enabling an agent-aware web experience via WebMCP is a vital goal for any learning platform going forward.

A Sample Flow

The idea of a Learning Surface is both an educational and a user experience design solution. For a coder, I've experimented with something that looks like this:

Clone a repo
Install the Agent Skill for the course into your AI agent
Connect the MCP server
Start the course and watch the introductory video
Interact with a slide
If you are in an IDE (or web IDE), read some code and ask questions about it
Ask a question mid-flow for clarification
Get asked a question about some code
Be asked to write some code
Get LLM feedback on the code
Have a mock debate with a fake coworker
Answer a quiz question
Time for lunch

Video and Screenshare

Thanks to MCP Apps and WebMCP video can and should still be a major building block of self-paced education. The human touch of an instructor's explanation, the power of animated visuals, and the practicality of observing an instructor's screen can't be overstated.

However, as part of a Learning Surface, video becomes a carefully weaved thread in the tapestry of the student experience. Video serves well to establish core mental models, share thoughtful advice, and provide a real human connection as a needed break from fake LLM interaction.

Designing a Learning Surface

Designing a Learning Surface, in my experimentation, is in some ways much like designing a self-paced video course, and far different in other ways.

It's similar in that you need a progressive curriculum. You need to create artifacts intended for consumption via MCP Apps or WebMCP. You need a voice, an intent, a goal, and technique.

It's vastly different in that it is a "surface" and not a straight line. If you want a learning experience to be more than "videos plus a chat bot", then you need to provide depth, delight, and aha-moments that can appear organically as the student moves through the experience.

This is especially challenging because good education, I believe, provides a progression that builds accurate mental models and foundations before moving on to fully using them.

You need to encourage a "golden path" through the material, while understanding that LLM interaction naturally means the student can do whatever they want.

Designing a Learning Surface is, at its core, a UX design challenge. You're designing for two simultaneous users (the student and the agent) across potentially non-linear paths, while maintaining progressive disclosure of concepts. The same principles that make a great product experience (clear mental models, meaningful feedback, guided autonomy) make a great learning experience.

The problem of skipping ahead is also not truly new. You could skip around a textbook in school. But I think the best Learning Surfaces will be those that provide meaningful education depth at all points on the Surface, whether the student chooses to dive into all of them or not.

After all, the best part about a human instructor is that you can ask them a question, and dive into their experience and opinions. Making your experience and opinions available to the student via LLM is a feat of context engineering that the best courses will muster.

Building a Learning Surface

Building a Learning Surface goes beyond screen recordings.

It's building tools, content designed for agent consumption, and interactive UI designed for "in the moment" student engagement.

Instructors should get good at context engineering, and teams supporting learning platforms and apps should provide an infrastructure and design and development support that delivers performant and well-tested Skill, MCP, MCP Apps and WebMCP-based experiences.

That said, one person can absolutely design and build a quality Learning Surface.

Observability

Good analytics are important for course content iteration. But because the LLM is along for the student experience ride, analytics on student experiences become more like interviewing a mentor than reading quiz results.

You can have the agent update student metrics and observations via the MCP server as the student takes the course. Have the LLM build a structured document as-you-go, and analyze the results. I found it enlightening and heartening.

For self-paced instruction you don't always get the enjoyment of watching the student learn and succeed. The AI can give you a play-by-play.

A Look Ahead at Self-Paced Learning

Maybe you were expecting me to sell you a Learning Surface at the end of this post. Well, I'm not. I'm sharing my ideas that I'm currently experimenting with.

By the way, nothing in my experimentation leads me to believe that AI will replace human-led instruction. It won't. It can't.

However, I do believe it is possible to deliver an impactful learning experience delivered via an AI agent. In fact, I think it's the future.

Events like the merger of Udemy and Coursera have people wondering about the future of self-paced education. But I think that self-paced online education isn't going anywhere. It's going to change, and we need to change how we think about learning experiences. But not about learning itself.

AI also doesn't remove the need for direct human instructor access. In fact, the possibility of AI inaccuracy increases it. Forums, office hours, and the like still are a vital aspect of self-paced education, no matter the format. But an LLM-powered format, properly designed, controlled, and presented, can be an impactful experience.

A great Learning Surface that serves as the foundation for people's careers won't come about because a new AI model is released. It will be carefully designed and thoughtfully curated by a human instructor who cares.

If you'd like to discuss or would like consultation on the future of technical education, feel free to reach out to me at hey@tonyalicea.dev, or connect with me on LinkedIn.

We're Losing Our Voice to LLMs

2025-11-27T00:00:00Z

We're Losing Our Voice to LLMs

Social media has become a reminder of something precious we are losing in the age of LLMs: unique voices.

Over time, it has become obvious just how many posts are being generated by an LLM. The tell is the voice. Every post sounds like it was posted by the same social media manager.

If you rely on an LLM to write all your posts, you are making a mistake.

Your voice is an asset. Not just what you want to say, but how you say it.

Your voice is unique. It is formed from your lifetime of lived experiences. No one's voice will be exactly like yours.

Your voice becomes recognizable. Over many posts it becomes something people subconsciously connect with, recognize, trust, and look forward to.

Your voice provides the framework for the impression you leave in a job interview, while networking at a meet-up, or with a co-worker.

Years ago I got a job thanks to my blog posts. A manager wanted my voice influencing their organization. Your voice is an asset.

Your voice matures and becomes even more unique with time and practice.

LLMs can rob you of that voice, and the rest of us lose something precious in the process.

Having an LLM write "in your voice" is not the same. Your voice is not static. It changes with the tides of your life and state of mind. Your most impactful message may come because it was the right moment and you were in the right frame of mind.

Let your voice grow with use. Let it be unique.

Do not let one of your greatest assets fade into atrophy, wilted by cognitive laziness.

Write in your voice.

I do not care what the linguistic remix machine juggles into being.

I care what you have to say.

I've Started Offering Live Coaching.

2025-10-15T00:00:00Z

I've Started Offering Live Coaching.

For over a decade students have asked me if I offer mentoring or live coaching. The answer has always been no. This year, in the age of LLMs, I made a decision: the answer is now yes.

I was uncertain if there would be a response to the offer of live one-on-one and team coaching. I was shocked when people immediately grabbed slots. What's more, it's been a fantastic experience so far.

Lessons Learned

As I've talked to developers of all ages and from all walks of life, many who have been taking my courses for years (and I've never met or talked to), I was struck by one simple fact: human connection is more important than ever.

In a time where many devs feel threatened by the guessing machines (LLMs), your humanity is the key to your success. Whether that's as a good worker, dev lead, or manager.

I've talked to those who are transitioning roles in some way, who are struggling to get the promised speed-up of AI (when the internet tells them they should be a 10x agentic dev), who feel unprepared for job interviews, or who simply aren't sure how to start their next project.

LLMs don't solve these problems. Humans do.

Feedback

I asked for feedback from some students after sessions, and I found the results personally quite touching. In the end, what they needed wasn't a code review or a technical recommendation, but a framework for thinking and existing as a dev in the age of AI.

They needed encouragement and validation. They needed their assumptions challenged. They needed a balance of reasonableness and practicality. They needed to overcome the emotional effects of marketing hype, and see their true value.

“I was paying for industry expertise and an outside opinion, but I also got your ability to empathize. Within minutes of listening to my situation and frustrations, you drilled down to the core issues which I needed to address in order to get unstuck... the session also surfaced some assumptions in other areas that I didn’t even realize I’d held.” — Zandra

Teams need to understand that clarity is more important than speed, and communication is the lifeblood of success. They need to understand how to solve the right problems, and mitigate the realities of AI risk.

For myself personally, I've also rediscovered my own value. I've been in dev and UX for 25 years. An online educator for over a decade. My experiences as a team and product lead, educator, and human dev have value. It's been so gratifying to share and see that experience help others.

“I booked a session to prep for an interview. He gave me a solid framework for how to approach the interview and helped me work through some technical areas I wanted to strengthen. What really stuck with me was how much more confident I felt afterward, I went in feeling ready.” — Helios

I've decided to continue to offer coaching into the foreseeable future. Happy to say multiple people have already booked a second session! You all have been students for so long. I'm so happy to hear your voices and see your faces. Times are changing and things are tough, and I'm so happy to help however I can.

Let's Talk

Slots for coaching sessions are open. You'll get a recording of the Zoom meeting and a copy of the whiteboard that we'll fill up during the session.

How can I help you?

Not Agile. Not Waterfall. With AI It's Cascades.

2025-08-19T00:00:00Z

Not Agile. Not Waterfall. With AI It's Cascades.

LLMs have changed software development. They can generate features in minutes that once took days, and large amounts of code that’s subtly wrong.

In the age of AI, our software development methodologies need to change along with our tools, taking advantage of the positives of LLMs while guarding against the downsides.

Waterfall was about writing comprehensive specs upfront, Agile is about building incrementally with minimal documentation.

AI-assisted development requires something in-between. Something that fosters good context engineering, utilizes LLM abilities to do things we could never do before, and pragmatically surfaces the dangers of probabilistic code generation.

This post describes how I think we should develop software in the age of AI. Not Agile. Not Waterfall. I call it Cascades.

cascade: /ˈkæskeɪd/; noun; a series of small waterfalls flowing from one to another.

Cascades are rapid AI-driven micro-waterfall development cycles that flow from detailed specifications through interactive prototypes to production code, with verification gates that scale based on business risk tolerance. They’re designed to give LLMs the context they need to work effectively while mitigating the quality risks of probabilistic code generation.

To adopt Cascade Methodology means embracing and understanding both the benefits and the dangers of AI-assisted development, and using it to your greatest advantage.

Waterfall and AI

Traditional Waterfall specs are too large and rigid for the rapid iteration that AI-assisted development enables. A major advantage of LLM code generation is the speed of iteration, and Waterfall simply doesn't take advantage of that.

Agile/Scrum and AI

Agile's intentionally minimal "just enough documentation" user stories can be poor context for an AI. An LLM needs guardrails and detailed specifications to avoid velocity-killing hallucinations and incorrect output.

At the same time, LLMs let you potentially implement far more features than you'd typically constrain a Scrum sprint to. However Agile has no metric to define how much LLM generation you can tolerate within a sprint, nor how much time verifying AI-generated code you can spare.

Agile is about quickly learning what does and doesn't work for your users, and AI-assisted development lets you learn more in an iteration. You can deploy bigger chunks of functionality with an LLM and thus get more feedback. But you also need spec details and code safeguards that Agile doesn't explicitly provide.

Cascade Methodology

With Cascade Methodology you iterate in development cycles. Each cycle is a micro-waterfall called a Cascade. With AI-assisted development I find it more useful to think in terms of specs instead of sprints, so a Cascade is the work done from spec to deployment.

The guiding principles of Cascade Methodology are:

Everyone has a seat at the table in writing specs.
Understand the underlying user and business problems the software should solve.
Build the least amount of software possible to solve those problems.
Prototyping and user research are first-class citizens.
AI-generated code is not to be trusted.
The density of code quality checks needed to deploy code is a function of the entropy tolerance of the business process the code is supporting.
Scope and timelines are functions of entropy tolerance and understanding the problems to be solved.

We will delve into each of these as we talk about the 5 phases of Cascade Methodology.

Phase 1: Spec

In Cascades, feature specs are detailed enough to give the AI clear context, but small enough to iterate quickly and adapt as you learn.

A good spec should include the usual business rules, data requirements, etc. But they should also include the why, not just the what. Those writing specs, via user interviews and observation, stakeholder meetings, and more should be good at getting to the "why" of the underlying problems that need to be solved.

Specs, especially those being written for LLM consumption, need to include constraints: design, functional, and technical requirements. That means more spec work up-front. But the speed-up that comes from providing good context to an LLM outweighs the time it takes to write a good spec.

Spec creation is good for your team. It should be a silo-breaking activity. It's the perfect place for multiple disciplines to have "seats at the table". Spec creation requires the cross-disciplinary work of requirements gatherers, designers, software architects, and more to arrive at well-engineered context for both the LLM and the team itself.

As Cascades are micro-waterfalls, specs should be for targeted features, usually not the entire app. However AI-assisted development in general let's you include more features in a spec than you might historically have included in a two-week sprint.

At all times, the underlying principle of building the least amount of software necessary should be front-of-mind. At times, once the underlying problem is understood, the solution may be no software at all, but a process change elsewhere.

Your spec is stored with your code (likely via a .md file) and is written for and provided to your LLM during prototype and production code generation. The first version of the spec is the entry point, but unlike Waterfall it's only a start.

The spec is a hypothesis, and thus doesn't have to be perfect. Once prototyped it becomes an experiment. Once verified, implemented, and deployed it becomes a source of truth.

Phase 2: Experiment

A lot has been said about how LLMs have impacted getting code to production. But the effects of LLMs on prototype creation is an absolute game-changer.

In a Cascade the "experiment" phase means prototyping and research.

Being able to generate true interactive prototypes (with locally stored data) for user research and usability testing is a true LLM superpower. Since you don't have to care about prototype code quality, designers and developers can vibe code their way through a spec, review free.

Quality context from the spec will enable the LLM to generate realistic data and scenarios, further enhancing the value of user testing.

The results of prototyping then feed back into the spec. You can have the LLM update the spec as the designer iterates on ideas, responding rapidly to the results of cognitive walkthroughs and user testing.

The SPEC -> EXPERIMENT -> SPEC loop should be fast. There's no need to spend time on code reviews. Ideate away.

Time spent on designing, testing, and iterating on prototypes is often the first thing to be neglected when teams are trying to move fast. But a good user experience is an important differentiator in the AI age, and with LLM generation, velocity is no longer an excuse not to research.

In fact, prototyping and research ultimately save time because prototypes can be purely vibe coded, no code quality required.

In the AI age building something is easy, but building something good is still hard. That's why prototyping and user research are first-class citizens in Cascade Methodology.

While it is preferable that prototypes be focused on a single Cascade, designers need to have a holistic view of software. Thus a single prototype may include features from multiple Cascades.

From a project management standpoint, this means the prototyping phase of a Cascade can be a cross-reference to a separate UI/UX task. In this way designers, through iteration and user research and testing, can ensure that various specs work together to form cohesive software workflows.

However, design should not be a bottleneck to learning, and perfect is the enemy of good. Designers can continue to easily experiment, but their priority should be solving user problems in some way, and getting that solution moved forward to implementation.

Phase 3: Implement

A combination of spec and prototype form fantastic context for both an LLM and developers.

Implementation choices is not a concern of Cascade Methodology. The guiding principle to keep in mind, again, is to build the least amount of software needed to satisfy the problems to be solved.

That doesn't mean devs should skip writing tests or best practices. Remember AI-generated code is not to be trusted.

Rather, it means everyone keeps in mind that the assumptions of the requirements and the design of the software are experiments that will be tested in the laboratory of actual code. So devs shouldn't get attached and shouldn't try too hard to predict the future.

At the end of implementation you should have a working software.

A Reality Check...

LLMs are statistical probability machines. AI-generated code may have edge case bugs, performance problems, security issues, regressions, and more.

Code needs to be verified before being deployed. But verification is nuanced, so before we can describe the next phase we need to pause and talk about Entropy Tolerance and Verification Gates.

Verification Gates

Cascades are a metaphor. We imagine a series of micro-waterfalls, each feeding into the other.

At the bottom of each micro-waterfall, we add a Gate. A Verification Gate is the quality checks on the AI-generated (and human) code prior to deployment.

In our metaphor, you should imagine a mesh gate, which can vary in its fineness. You can have a porous gate or a dense gate.

With AI-assisted development we measure the density of checks needed as a function of the feature's Entropy Tolerance.

Entropy Tolerance

Entropy Tolerance is how much uncertainty (or AI-generated 'guesswork') a software-supported process can handle.

LLMs are powerful, but inherently unreliable, probabilistic guessing machines. "Entropy" in this context is the uncertainty in a probability distribution.

The core question for any Cascade is: what is the Entropy Tolerance of this feature? The lower the Entropy Tolerance the denser the Verification Gate must be, the higher the Entropy Tolerance the more porous it can be.

For example, suppose scroll animations are being added to static web pages on a large website. The Entropy Tolerance may be quite high. If the AI-code isn't perfect, it won't have great impact on the underlying process the software is supporting as long as the feature "works".

It may be sufficient for human review of a portion of the site, not every line of code. In this case, an LLM agent may be given the task of updating all the pages, and the Verification Gate can be "porous", meaning few or cursory human checks of the code.

The more porous the Gate, the more "vibe coded" a feature may be. Things are allowed through the gate more easily. Of course Cascades are like a river with a series of waterfalls. That same code will still be there in later iterations, so code quality is still a concern. That's why good specs are so important.

You might have automated code reviews in your process via LLM. But until there is a human in the loop, you should still consider your gate porous.

On the other hand, a feature that involves personally identifiable information of users has a low Entropy Tolerance. Bugs or security holes would have a large impact on the underlying processes the software is supporting (like user's lives and business health).

Thus the Verification Gate in this case would need to be dense. Human-in-the-loop checks of code are required. AI-generated code is not trusted. Less vibes, more PR reviews.

You should determine the Entropy Tolerance of a feature during the spec phase of a Cascade. This is a great opportunity to involve both your domain and security experts in the spec process.

That all said, we can define the final two phases of Cascade Methdology.

Phase 4: Verify

The feature implementation is verified according the Entropy Tolerance of the process it supports.

This could range from QA-style checks of the running software to human-in-the-loop complete code reviews.

In reality, the implementation and verification phases are often in a loop across multiple code merges.

You shouldn't waste much time isolating which code is AI-generated (though running agents that make PRs may make this obvious).

The Verification Gate being porous or dense applies as much to human code as AI-generated. The point is that you are aware of the needs of and dangers inherent to deploying the feature.

Phase 5: Deploy

Deploy via whatever methodology works for your team. I recommend Continuous Deployment, but only integrate code that passes the Verification Gate, whether porous or dense. CI/CD in a gated context.

You aren't really doing anything you didn't do before if you are reviewing code before merging and engage in CI/CD. You are just more explicitly aware of AI-generated code as a danger to quality.

To recap, then, the phases of a Cascade cycle are:

1. SPEC ←──────────────┐
   ↓                   │
2. EXPERIMENT ─────────┘
   ↓
3. IMPLEMENT ←─────┐
   ↓               │
4. VERIFY ─────────┘
   [porous or dense]
   ↓
5. DEPLOY

This lays out the complete methodology. But any experienced team will ask two questions: how do you maintain a reasonable scope in Cascade Methodology and how do you control the timeline?

Scope

Avoiding scope creep is an issue of defining the problems to be solved in a development cycle, rather than specific features (features are just solutions to problems). You should avoid the flawed concept of MVPs and focus releases on MSPs (Minimum Solved Problems).

An MSP set is a subset of user and business problems that need to be solved by the software in some way. This approach allows for cross-disciplinary and mental flexibility in what features really need to be built.

You don't get attached to a feature idea in an MSP set, or blindly implement solutions users and stakeholders suggest. You get attached to solving the real underlying problems with the least amount of software possible.

For example, an MVP for a todo app might be framed as a list of features: "add tasks, mark tasks complete, delete tasks, send email reminders for due dates." An MSP, on the other hand, starts with a list of problems: "users need a way to remember tasks, know what's done vs. not done, and need to know when tasks are due."

Once you frame it this way, the scope can shrink dramatically. The third requirement might be satisfied in an MSP release, not by building a custom email reminder system, but by simply giving users the option to add a task as an event to their existing calendar. By defining problems instead of features you build less software, move faster, and avoid locking yourself into unnecessary complexity.

AI-assisted development makes it easy to quickly create huge amounts of code. This can augment scope creep, security threat surface size, technical debt, and more. The mindset of building the least amount of software possible is an important counterpoint to the dangers of AI-assisted development.

That said, scope is variable in Cascade Methodology. Scope is a function of Entropy Tolerance and the chosen "problems to be solved" by the software.

Why a function of Entropy Tolerance? Because AI-assisted velocity changes depending on the bottleneck of needed human verification. A dense Gate necessarily slows down the waterfall.

In our previous example, the scope of adding scroll animations to an existing site could be quite large. An LLM agent could update hundreds of pages. Since the Gate is porous, letting more "AI slop" through, the Cascade can handle a larger scope.

For denser verification requirements, the scope is constrained by what humans can reasonably check. This may also vary depending on the complexity of the feature. Straightforward CRUD pages may be human-checked more quickly than complex business rules.

What about "problems to be solved"? They influence the scope by shrinking it. You build only what you need (if anything) to solve the user and business needs.

Thus solving problems with the least amount of software possible, combined with AI-assisted developer velocity, can result in a massive scope of "solved problems" for each release.

Your users and stakeholders don't care about how many lines of code you deployed this week. They don't actually care about how many features you've deployed. They care about how many of their problems you've solved.

Timelines

Experience has shown that the amount LLMs increase velocity of implementation is dependent on how good the specs you give them are. Thus the upfront focus on cross-disciplinary spec creation and rapid prototyping and research.

In general the stakeholder question of "how long will this take" is a function of the supported process' entropy tolerance and and how well the underlying problems being solved have been flushed out.

If you understand the underlying problems each Cascade's features are solving you can prioritize your Cascades by business need and, as we said before, minimize the scope to as small a feature as possible that solves the problem.

Minimizing the scope reduces the timeline.

For example, a stakeholder may ask for a way to automate emailing data in a web app. You flush out that the underlying problem is quickly sharing data. So you design a Cascade to ensure your UI's URLs are unique and shareable and add a Share button to your screens. The spec is detailed, the feature itself is far smaller than requested.

It turns out that LLMs do a decent job of identifying these kind of alternative solutions if you give them the complete context of a feature request. You should use AI to brainstorm and help you minimize the amount of code needed for a solution. It may dramatically improve your velocity.

I find that some teams use Scrum sprint timelines as an attempt to artificially compensate for poor understanding of underlying user and business problems. Some might say that's the point.

But a lack of user research followed by building bigger-than-needed, or outright not-needed, software in a sprint does not mean you're more efficient or flexible.

If you understand the underlying problems well, you end up writing less software, timelines naturally shrink, and stakeholder and user satisfaction increases. That's why Cascade Methodology doesn't have explicit timeboxed sprints like Scrum.

You can have multiple Cascades running in parallel where each sits at different phases in the process. Coordinate them however makes sense for your team. But if you prioritize understanding over timeline, and keep your Cascades sized according to Entropy Tolerance, velocity will stay high.

You don't aim to control the timeline. You aim to control the software.

Learning

Like Agile, Cascade Methodology embraces learning as-you-go, but utilizes AI to expand the scope of learning by expanding the scope of the release when possible.

Even after deployment, the spec is both a source of truth and living documentation of a continuing education in what the software needs truly are.

You should then respond to what you learn. The ability to pivot is also a key feature of Agile, and one that Cascades encourages as well. You learn a lot in the experiment phase. You learn even more when the feature is live.

A Cascade is just a moment in time. Don't consider its results permanent. The river keeps flowing.

Methodology for the Modern Era

The age of AI has changed software development in many ways. But LLM marketing hype has also clouded the impact of their downsides.

Cascade Methodology aims to be a practical, realistic approach to modern AI-assisted software development that takes advantage of LLM positives and mitigates LLM negatives, balancing good software with high velocity.

If you'd like to discuss, contribute, or support with a star, check out the official GitHub repo.

I hope these concepts help you and your team successfully build something great.

Happy coding!

It's Not Context Engineering, It's Context Authoring

2025-08-12T00:00:00Z

It's Not Context Engineering, It's Context Authoring

When working with LLMs we shouldn't call it "context engineering", we should call it "context authoring".

Words matter, because they help us set proper mental models and expectations. When it comes to LLM context, engineering sets an incorrect mental model, while authoring puts you in the right frame of mind.

The two concepts are distinct:

Engineering

Building rigid systems following strict protocols
Following technical specifications and repeatable processes
Solving problems through logical debugging
Refining for consistency and error reduction

Authoring

Building structured content guiding interpretation
Following principles of hierarchy and clear communication
Solving communication challenges by providing examples
Refining for clarity and intended outcomes

Saying you are engineering context, like prompts, implies you achieve a predictable outcome through rigorous iteration and testing. That's setting a poor expectation. LLMs aren't programmable systems in the traditional sense, and their output is anything but predictable and repeatable.

Authoring is instead about communication. You get the best results from LLMs by thinking in terms of authoring content for comprehensibility and constraints.

When you write context for an LLM, you're crafting communication that guides its pattern-matching nature to respect your intent, constraints, and desired outcomes — the same as writing clear documentation or instructions for a human collaborator.

Giving an LLM a role to play, patterns of example output, background reasoning, specific instructions, and more are not engineering. You are triggering pattern matching in a system derived from human communication.

That includes code, as code is a form of communication. Code is a grammatical structure with the purpose of communicating intent to a human or system. Good code is good communication, because the intent is understood correctly.

Your input into the communication-trained machine, whatever it is, needs to be good communication. And that, in turn, is what the LLM will attempt to infer as output: the structure of good communication (whether correct or not).

On average, the better the communication input, the closer the communication output will adhere to your intent.

The industry may have settled on engineering as a term, but I encourage you to think in terms of authoring. You'll get the best results from your efforts.

Entropy Tolerance: The Essential Software Question for The AI Age

2025-04-04T00:00:00Z

Entropy Tolerance: The Essential Software Question for The AI Age

"Entropy Tolerance" is the concept we should be using to talk about AI-assisted development, software requirements, and team processes in the age of LLMs and "vibe coding."

I've been thinking a lot about how AI is changing the way we build software—not just writing code, but shaping whole workflows.

So I've coined a phrase: Entropy Tolerance.

"Entropy Tolerance" is how much uncertainty (or AI-generated 'guesswork') a software-supported process can handle.

Every process—whether you're prototyping a new idea or managing a supply chain—has a limit to how much uncertainty it can tolerate before things break.

In information theory, entropy (as coined by Claude Shannon, whose mathematical ideas have shaped LLMs) measures uncertainty in a probability distribution. LLMs are built on this foundation. Every output they generate is a probabilistic, statistical guess.

The more AI you integrate into your process—from brainstorming to coding to QA—the more entropy you introduce. As entropy increases, confabulations (that is, hallucinations) and unexpected outputs compound. When probabilities multiply, uncertainty grows.

A Useful Vocabulary

Good decisions come from clear thinking—and clear thinking needs clear terms. "Entropy tolerance" gives devs, managers, and orgs a way to talk about how much unchecked AI involvement a process can handle.

For devs, realize that we aren't talking about the entropy tolerance of the act of coding itself. Rather the entropy tolerance of the processes that the code is supporting. This touches both how we code, and any AI integration we include in the software.

Requirements, "Vibe Coding", and Entropy Tolerance

When you begin any software project, ask yourself this question: What is the entropy tolerance of the process this software is supporting?

The higher the tolerance, the more it can tolerate AI being occasionally wrong. This is the new key software requirements question that should be asked going forward.

This also guides coding and design decisions. If a process has a low entropy tolerance, then you should ensure the software's design enables and encourages humans to check the AI's work.

If a process has a high entropy tolerance, then you can allow AI to do more work with less oversight, such as "vibe coding" a feature.

Here are some concrete examples:

You're building a prototype for user testing, but the code won't be deployed to production.

Entropy tolerance: ⬆️ High
Since the generated software isn't going into production, it doesn't matter what the underlying process is, the entropy tolerance is quite high. If the AI gets something wrong, it won't have much of an impact.

You're adding a feature to your software that extracts data from a PDF.

Entropy tolerance: Could be ⬆️ High or ⬇️ Low
Remember to focus on the underlying process. If you are extracting financial data from a PDF that will go into a payroll system, for example, the tolerance is low.

If the tolerance is low, you'll need to make it clear to the user that the data extracted needs to be reviewed, and should provide a UI that helps with that review.

If the tolerance is high (say, extracting keywords to build a word cloud), you may be able to simply have the AI do the work and move on with minimal human checks.

You're adding a feature to medical software that logs symptoms a patient reports to their doctor.

Entropy tolerance: ⬇️ Low
You have to get this process right. The cost of LLM mistakes could be terrible. This is not the place to vibe code. You might use AI to assist in coding, but it would be done slowly, carefully, and with constant oversight.

Any AI integration in the software itself would be made extremely clear (perhaps with warnings) to the user, and never allowed to be completed without explicit human sign off.

AI Won't Replace Developers

Entropy tolerance also shows why probabilistic AI won't replace developers. So many of the processes we support in software have low entropy tolerance.

Sure, a non-coder can vibe code a minesweeper clone for their blog. The entropy tolerance of that is sky high. But what about enterprise software? What about a SaaS app?

No matter what the hype says, at their mathematical core, LLMs are unreliable. They make a best guess based on what's been done before. That can be incredibly useful and powerful. But it's also a risk factor for any business.

For processes with low entropy tolerance, software needs human coders. Human coders to check AI work. Human designers to design AI integrations that encourage human input.

Conclusion

The next time you're starting a software project, ask yourself: "What's the entropy tolerance of this?" Understanding the limits around uncertainty and AI involvement can be the difference between costly mistakes and remarkable success.

Generative Rapid Prototyping (GRiP)

2025-01-16T00:00:00Z

Generative Rapid Prototyping (GRiP)

Prototypes save time and money. You can test and present ideas, iterate, and provide specifications to developers. Traditional tools like Figma are great at this. But AI has brought about a new approach that I'm finding to have unique advantages.

I think it's useful to name things, so I'm calling it Generative Rapid Prototyping (GRiP) (as in "get a grip" on what you're going to build). The goal is to leverage AI to create multiple testable, interactive prototypes in hours instead of days.

What Is GRiP?

Traditional prototyping tools excel at visual design but fall short when it comes to testing real user interactions. Static mockups can't reveal how users actually interact with your application, and high-fidelity prototypes often require significant investment before gathering meaningful feedback.

Generative Rapid Prototyping takes a different approach: use AI-powered code generation to quickly create functional prototypes that users can actually test. These prototypes aren't just clickable mockups – they're working web applications with real interactivity and local data persistence.

Designers and developers have been discovering this approach for awhile now, and I wanted to lay out a set of principles that I've found to be the useful in designing prompts and getting the best results from AI-generated prototypes:

The 9 Principles of GRiP

1. Generative Speed

Principle: Prototypes should take hours, not days to create.

Modern AI tools can generate functional UI components, forms, and interactions very quickly. Combined with lightweight styling frameworks, testable prototypes can be created in a fraction of the traditional time. This means more time for iteration and less time wrestling with tools.

Focus on setting up an environment and prompts that encourage rapid iteration. Your goal is to figure out the problems you need to solve and how to solve them. Generative AI isn't going to get you pixel-perfect design. Pixel-perfect designs can come after.

2. Testable Interactivity

Principle: Simulate real-world user flows with basic interactivity.

Instead of simulating interactions through linked screens, prototypes handle real user actions. Users can add items to a cart, edit their profile, or filter search results – just like they would in the final product. This level of interactivity reveals usability insights that static mockups might miss.

3. Realistic Data Generation

Principle: Populate prototypes with believable, diverse data.

AI excels at generating realistic test data that reflects your user base. Populate your prototype with:

Diverse user profiles and avatars
Realistic product descriptions and prices
Varied content lengths and formats
Multiple languages and cultural contexts

4. Local Data Persistence

Principle: Maintain prototype state across sessions.

When users interact with your prototype, their actions should persist between page refreshes and browser sessions. This creates a more realistic testing environment and allows for longer-term usability studies. Users can return to their saved state, just like in a real application.

5. Edge Case Simulation

Principle: Test realistic scenarios, including errors and outliers.

Good design accounts for everything that could go wrong. Prototypes should handle:

Empty states and zero-data scenarios
Loading and error states
Content overflow and truncation
Network connectivity issues
Invalid user inputs

6. Accessibility by Default

Principle: Ensure prototypes are inclusive and usable for everyone.

Accessibility shouldn't be an afterthought. Prototypes should:

Use semantic HTML
Work with screen readers
Support keyboard navigation
Maintain proper contrast ratios
Include clear error messages
Handle text scaling
Provide alt text for images

7. Rapid Feedback Loops

Principle: Build prototypes that allow for fast iterations.

Prototypes can be modified extremely quickly in response to user feedback. This means:

Immediate implementation of user suggestions
Real-time A/B testing
Quick iteration on interaction patterns
Direct observation of user behavior

Tip: AI sometimes is bad at changing only one aspect of an app without inadvertently changing other things. Keep each iteration of your prototype in a separate branch of a source control repository, like GitHub, so you can revert if the AI goes a bit rogue.

8. Match Technologies

Principle: Use the same tech stack as your production environment.

By prototyping with your target technologies, you can:

Validate technical feasibility early
Test actual platform constraints
Reduce the design-to-development handoff friction
Reuse as much AI-generated code as possible

9. Deployment-Ready Prototypes

Principle: Prototypes should be easily shareable and testable.

Make your prototypes accessible to stakeholders and testers:

Deploy to web hosting platforms
Enable easy sharing via URLs
Support multiple devices and browsers

Getting Started with GRiP

To begin implementing GRiP in your workflow:

Choose your tools:
- An AI coding assistant
- A lightweight CSS framework or vanilla CSS
- A modern JavaScript framework (AI tends to be good at them because it has lots of training data)
- Basic data storage solution (localStorage or indexedDB)
- A storage and deployment solution (where you can separately store each iteration)
Create a starter template for the AI to work from:
- Basic navigation structure
- Brand colors and fonts in a base CSS file
- Common UI components (optional)
Use AI to accelerate:
- Component creation
- Test data generation
- Interaction patterns
- User research

Once you have a well-working prototype that both dev and design feel good about, you likely still will need to work on getting the design just right. This approach is about accelerating prototyping and working out what you should build.

Prompt Guidance

When prompting an AI to build your prototype be sure to specify:

to use semantic HTML and be accessible
a CSS approach (Pico CSS, Tailwind, Vanilla CSS, etc.)
a JavaScript framework
data is just JS objects in local storage, no DB or fetching from APIs
what kind of data you need to be generated
what empty and error states should be represented
to only change the elements of the prototype that you direct it to during iteration

The Future of Prototyping

GRiP represents a shift from static, visual-only prototypes to functional, testable applications.

By embracing GRiP, teams can:

Validate ideas faster
Test real user interactions earlier
Reduce the prototype-to-production gap
Make more informed design decisions

Conclusion

Generative Rapid Prototyping isn't just some new tool – it's a new prototyping approach. By leveraging AI and modern web technologies, we can create better prototypes faster, leading to better products and happier users.

What should be your first step? Start by converting your next prototype from static mockups to a functional web application with local data storage. Choose a tool for generating the web application, whether it's bolt.new, v0, Replit, Lovable, Cursor, or another.

Set up easy ways to deploy. For example you can set up a GitHub repo and deploy quickly to StackBlitz.

The time you invest in setting up your GRiP workflow will pay dividends in faster iterations and better user feedback.

Understanding React Server Components

2025-01-14T00:00:00Z

Understanding React Server Components

React Server Components have lifted server-rendering to be a truly first-class citizen of the React ecosystem. They allow developers to render some components on the server, while attempting to abstract away the divide between the client and server. Devs can interleave Client and Server Components in their code as if all the code was running in one place.

Yet, abstractions always come at a cost. What are those costs? When can you use RSCs? Does reduced bundle size mean reduced bandwidth? When should you use RSCs (React Server Components)? What are the rules that devs have to follow to use them properly and why do those rules exist?

To answer these questions, let's dive together into how React Server Components really work, under-the-hood. We'll do this by examining two sides of the RSC story: React itself and React meta-frameworks. In particular, we'll look at both React and Next.js internals to form an accurate mental model of how the RSC story comes together.

Note This post is aimed at developers who are familiar with using React. It assumes you know what components and hooks look like.

It's also assumed you're familiar with Promises, async, and await in JavaScript.If not, you can watch my under-the-hood YouTube video on Promises, async, and await.

First, we must establish some fundamentals necessary to understanding how RSCs work.

The DOM and Client Rendering

React co-opted the term "render". When we say the browser "renders" our page we are referring to the actual work of painting the DOM to the screen. The browser takes the DOM (the tree of elements) and the CSSOM (the tree of computed styles), calculates how elements should be laid out, and then paints the appropriate pixels to the screen.

React instead uses that same term to mean "calculating what the DOM should look like". The values our component functions return tell React what the DOM should look like.

Thus, in the world of React (and other frameworks who have since followed in React's footsteps), when we say "client rendering" we're talking about our component functions being executed in the browser.

React's version of "rendering" doesn't always lead to actual browser rendering, since it's possible the DOM already looks the way React thinks it should.

When React says "client rendering" we're talking about our component functions being executed in the browser.

In fact, a major point of React's core architecture (along with all other JS frameworks) is to limit how much its internal code updates the DOM.

Tree Reconciliation

Inside React's source code are calls to browser DOM APIs like appendChild to update the DOM in the client. React chooses when to execute those browser DOM APIs via tree reconciliation and diffing.

As we talked about in my post on React Compiler, React keeps track of what the DOM both currently looks like and should look like in a tree of JavaScript objects, where each node is called a Fiber.

React calculates what the DOM should look like (called "Work-In-Progress") and compares it to what the DOM currently looks like (called "Current") in two branches of that JavaScript object tree.

It then reconciles the difference between those two trees, calculating the steps needed to convert the current tree into the work-in-progress tree. Those steps are the "diff" or "patch".

Once it finishes that calculation, all against simple JavaScript objects, it knows what steps to take in the real DOM. By finding the minimum number of steps to take, it minimizes how much it has to update the DOM, since updating the DOM is expensive and causes the browser to re-render (layout elements and paint pixels).

Updating the DOM in the client has the advantage of preserving state as you update the UI. For example, a user can type information into a form, React can update the UI based on some event, and the text stays in the form (unlike if the page refreshed).

Thus React is focused on updating the DOM in the client, while trying to be as efficient as it can in doing so, doing work first against a fake DOM. This fake copy of the DOM's structure in JavaScript is generally called the "Virtual DOM".

Is "Virtual DOM" the Right Phrase? We used to call the collection of JavaScript objects in React that are structured like the DOM the "Virtual DOM". But React doesn't like that term now because you can target other things like native iOS and Android apps (React Native) to render to.

In fact, there are multiple trees that React deals with, a tree of React Elements (JS objects) that your function components return and a Fiber tree (also JS objects) that React Elements are converted into and used to store state among other things.

While I usually refer to these two trees more specifically, for this post I'll use the long-standing colloquial term "Virtual DOM" because it's useful in keeping track of how RSCs work.

Calculating the Virtual DOM is what React refers to as "rendering": executing your function components to determine what the real DOM should look like. This all happens inside the JavaScript engine executing the functions, and until reconciliation doesn't touch the real DOM at all.

As it turns out, understanding that React co-opted the term "render" goes a surprisingly long way in helping explain RSCs accurately.

To understand RSCs we need to have clear in our minds the difference between what we usually mean in web dev by client and server rendering, and React's focus on the generation of the Virtual DOM.

When React says "render", you don't actually necessarily see anything happen...

Let's keep track of these various "render" meanings as we go. We'll call the typical (non-React) definitions "classical" and start building a dictionary entry for our web dev vocabulary:

rend·er: /ˈrendər/; verb; 1. (Classical Client-Side) To take the DOM and CSSOM, compute layout, and paint pixels to the screen.; 2. (React Client-Side) To execute function components in order to build and update the Virtual DOM.

The DOM and Server Rendering

Moving forward in the RSC story means moving backwards in time. A core idea of the internet has long been HTML being delivered from a server.

Creating your HTML on the server (perhaps using server technologies like NodeJS or PHP) is classically called "server-side rendering" or "server rendering". This is already different than what we meant by classical client rendering. Historically server rendering has meant "generate strings of HTML" on the server.

This comes with some advantages. Browsers translate HTML into the DOM very quickly. As a result HTML renders in the browser fast. Updating the DOM via JavaScript is slower in comparison. Also, your server is closer to your database or file storage, so those operations are more efficient.

A downside is that, while the client can request the HTML again, you lose state (the page refreshes).

This has been the balancing act for many years in web development: server-rendered HTML appears quickly, but DOM updates via client-side JavaScript let you make changes while maintaining the state of the page.

React doing both is nothing new. While React does DOM updates via client-side JavaScript, developers have long been able to server-render React components (SSR) as well.

Master React From The Inside Out

If you are enjoying this deep dive, you'll love and benefit from understanding all of React at this level. My course Understanding React takes you through 17 hours of React's source code, covering JSX, Fiber, hooks, forms, reconciliation, and more, updated for React 19.

Learn More →

The server (running its own JavaScript engine via something like NodeJS) executes the components and generates an HTML string to send to the client, but there's a big caveat: all the JavaScript code for those same components also had to be sent to the client and executed.

Why? So the Virtual DOM could be built from what those function components return. The Virtual DOM is used to "hydrate" the real DOM, meaning for example we know what click event inside what function component to run when a button is clicked. Remember, React needs both trees (DOM and Virtual DOM) to exist in the client to work. So, SSR in React means executing your functions twice (once on the server to make HTML and once on the client to make the Virtual DOM).

Here's a visualization of the SSR/hydration process to help:

Enter React Server Components. RSCs add the ability to intermingle React components that execute on the server with React components that execute on the client without sending and re-executing the server components' JavaScript code. This also comes with the possibility of initially rendering HTML on the server, before beginning to update the DOM in the browser.

How?

First, let's update our dictionary entry:

rend·er: /ˈrendər/; verb; 1. (Classical Client-Side) To take the DOM and CSSOM, compute layout, and paint pixels to the screen.; 2. (React Client-Side) To execute function components in order to build and update the Virtual DOM.; 3. (Classical Server-Side) To generate HTML to be sent to the client to build the DOM.; 4. (React Server-Side SSR) To execute function components in order to generate HTML to be sent to the client to build the DOM.

What About Server-Side Generation? One thing we aren't talking about here is SSG (Server-Side Generation). That means pre-generating the HTML while building the app (that is, preparing it for deployment). You can do this for both Client and Server Components.

SSG would have the same definition as SSR in our dictionary entry. Differentiating SSG and SSR doesn't help us much in this post, so I won't talk about it much, but it is supported.

We said React needs both full trees, DOM and Virtual DOM, to be sitting in the browser's memory to work. So how do React Server Components get away with only executing on the server, without needing their JavaScript code to be downloaded and executed by the client?

React needs both full trees, DOM and Virtual DOM, to be sitting in the browser's memory to work.

In other words, how does React build the Virtual DOM in the browser for the part defined by functions executed on the server?

Flight

In order to support executing function components on the server, and then building the Virtual DOM from their results on the client, React added the ability to serialize the React Element tree returned from server-executed functions.

Serialization and deserialization often end up meaning "convert objects in a computer's memory into a string" and "convert strings back into objects in a computer's memory".

In this case, the results of our component functions need to be serialized and sent to the client.

Let's suppose I'm making a simple app where I will track how many students have enrolled in my React course. I'll start with a basic RSC in Next.js. It will be executed on the server.

export default function Home() {
  return (
    <main>
      <h1>understandingreact.com</h1>
    </main>
  );
}

Isomorphic Components If a component can be executed on the server or the client it's referred to as "isomorphic". My above function doesn't do anything server-specific (like connect directly to a database or read a file off the server), so it could instead have been executed on the client, and React could build the Virtual DOM from its results directly as normal.

If a function is isomorphic, then it can be shared. Both Server and Client Components can import and use them.

To prevent having to send this function to the client for execution, its results need to be serialized. Inside React's codebase this serialization format is called "flight" and the sum of data sent is called the "RSC Payload".

My simple function's result ends up serialized into this:

"[\"$\",\"main\",null,{\"children\":[\"$\",\"h1\",null,{\"children\":\"understandingreact.com\"},\"$c\"]},\"$c\"]"

Let's format it for easier examination (credit for the excellent RSC parser from Alvar Lagerlöf):

{
  "type": "main",
  "key": null,
  "props": {
    "children": {
    "type": "h1",
    "key": null,
    "props": {
      "children": "understandingreact.com"
    }
}

Can you see the structure of the Virtual DOM? Our main and h1 elements are here as well as our plain text node. We can see what is being passed as props, specifically the standard "children" prop intrinsic to React.

We're simplifying here, there's more to the format than this, and a meta-framework may add more to it for their own purposes. For example, identifiers for what kind of thing is being placed in the tree "like 'f:' for 'flight'". But a simplified example is sufficient for our understanding.

While React is providing the serialization format, the meta-framework (in this case Next.js) must do the work of ensuring the payload is created and sent to the client.

Next.js, for example, has a function in its codebase called generateDynamicRSCPayload.

The meta-framework is ensuring that the payload is generated and sent to the client. Thanks to the payload, on the client React can build an accurate Virtual DOM and do its normal reconciliation work.

Meta-Frameworks and Server Rendering

We said earlier that rendering HTML from RSCs was a "possibility". That's because it's optional - it's up to the meta-framework if it does so or not. But it makes sense to do so.

Remember we said perceived performance was an important metric. If you're already executing code on the server, and you can stream back HTML, you should, because the browser will render that HTML quickly, resulting in a faster perceived experience for the user.

If a meta-framework is perceived as slow, no one will use it. So React meta-frameworks implementing RSCs need to do both kinds of server rendering: the classical kind and the React kind.

Classical server rendering (generating HTML) gets you pages that render (painted by the browser) quickly, while React-style server rendering (RSC payload) gets you the Virtual DOM for future stateful updates.

Thus, in practice, an RSC will result in what is called the "double data problem". You will send the same information from the server in two different formats at the same time: HTML and Payload. You're sending the info needed to immediately build the DOM (HTML) and the Virtual DOM (Payload).

Here's a visualization:

For our simple example, Next.js returns HTML, which the browser uses to build the DOM:

<main>
  <h1>understandingreact.com</h1>
</main>

and the Payload, which React uses to build the Virtual DOM:

{
  "type": "main",
  "key": null,
  "props": {
    "children": {
    "type": "h1",
    "key": null,
    "props": {
      "children": "understandingreact.com"
    }
}

The HTML being sent allows the page to be browser rendered quickly. The user sees something right away. The Payload being sent lets React finish the work of making the page interactive.

Sometimes it's argued that the cost of this repetition of data is negated by compression algorithms (like gzip) which servers use before sending responses. However, HTML and the JSON-ish payload are two different formats, so the repetition is obfuscated enough that the double data still makes an noticeable impact on bandwidth.

Abstractions have a cost. The cost here is sending the same information twice.

With all this in mind, though, we now have a complete list of 5 different definitions for "render"!

rend·er: /ˈrendər/; verb; 1. (Classical Client-Side) To take the DOM and CSSOM, compute layout, and paint pixels to the screen.; 2. (React Client-Side) To execute function components in order to build and update the Virtual DOM.; 3. (Classical Server-Side) To generate HTML to be sent to the client to build the DOM.; 4. (React Server-Side SSR) To execute function components in order to generate HTML to be sent to the client to build the DOM.; 5. (React Server-Side RSC) To execute function components in order to generate flight (payload) data to be sent to the client to build and update the Virtual DOM.

Notice similarities across the React definitions? For React rendering always means "executing function components", and Client and Server Components both provide what is needed to build and update the Virtual DOM.

Streams, Suspense, and RSCs

Performance is always a concern when building an application. But there are two kinds of performance: actual performance and perceived performance.

HTTP and browsers have long supported streaming as a way to improve both kinds of performance. Things like NodeJS' Stream API and the browser's Streams API (in particular the browser's ReadableStream object).

React (and any meta-framework that wants to support RSCs) utilize these core technologies to stream both HTML and Payload data. Streaming really means sending small amounts (called chunks) at a time. The client can work with those smaller amounts of data as they come in.

Thus with streams the question isn't "what was sent" but "what has been sent over time".

The browser is designed to handle HTML streaming over the network. It renders (lays out and paints) the page as HTML streams in.

Similarly, React accepts a Promise which later resolves to RSC Payload data. Next.js, for example, sets up a ReadableStream on the client, reads in the stream from the server, and gives it to React as it comes in. React's entire approach to server rendering is centered around streaming content in where needed.

In fact, the Flight format itself includes markers for things that haven't completed yet. Like Promises and lazy loading.

For example, suppose I setup a server component to be async, and await a timer:

// components/Delayed.js
async function delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

export default async function DelayedMessage() {
    await delay(5000); // 2 second delay
    
    return (
        <p>This message was loaded after a 5 second delay!</p>
    );
}

// page.js
import DelayedMessage from "./components/DelayedMessage";

export default function Home() {
  return (
    <main>
      <h1>understandingreact.com</h1>
      <DelayedMessage />
    </main>
  );
}

The async function returns a Promise. Thus the resulting Payload will look like this:

{
  "type": "main",
  "key": null,
  "props": {
   "children": [
    {
     "type": "h1",
     "key": null,
     "props": {
      "children": "understandingreact.com"
     }
    },
    {
     "$$type": "reference",
     "id": "d",
     "identifier": "L",
     "type": "Lazy node"
    }
   ]
  } 
}

Notice that the place where the DelayedMessage component should be is instead marked with a special "L" identifier, marking a place where content will appear later.

If you run this code, though you'll find that instead the entire page takes 5 seconds to load, rather than just the delayed message.

That's because React deals with Promises and lazy loading using the special Suspense functionality designed for the client. If we update our component to use Suspense:

import DelayedMessage from "./components/DelayedMessage";
import { Suspense } from "react";

export default function Home() {
  return (
    <main>
      <h1>understandingreact.com</h1>
      <Suspense fallback={<p>Loading...</p>}>
        <DelayedMessage />
      </Suspense>
    </main>
  );
}

and we run the page, it will instead show the fallback first and then show the delayed message after 5 seconds. But notice this component still runs on the server! How can you opt into Suspense on the server? You don't. The Payload returned from the function, when processed on the client, builds a Virtual DOM that includes a boundary.

The Payload looks like this:

{
  "type": "main",
  "key": null,
  "props": {
   "children": [
    {
     "type": "h1",
     "key": null,
     "props": {
      "children": "understandingreact.com"
     }
    },
    {
     "type": {
      "$$type": "reference",
      "id": "d",
      "identifier": "",
      "type": "Reference"
     },
     "key": null,
     "props": {
      "fallback": {
       "type": "p",
       "key": null,
       "props": {
        "children": "Loading..."
       }
      },
      "children": {
       "$$type": "reference",
       "id": "e",
       "identifier": "L",
       "type": "Lazy node"
      }
     }
    }
  }
}

Notice both the fallback (as a prop) and what is loaded after the Promises resolves (the "Lazy node", in this case the DelayedMessage) are all there.

The Payload both itself streams in in chunks and references spots in the Virtual DOM where Promises will later be resolved. In this way React and RSC-supporting meta-frameworks endeavor to improve both real and perceived performance for the user, letting the user see UI as soon as possible.

But where does flight data stream to really? It must be somewhere in the React codebase.

Giving React the Payload

To support RSCs, React added to its codebase the ability to accept the Flight format (a string) and convert it to React Elements in functions like parseModelString.

It's up to the RSC-supporting meta-framework to execute those React APIs, sending the appropriate data.

For example, Next.js adds some extra wrapping components to your app, where it passes in a stream of Payload data.

It looks like this:

<ServerRoot>
  <AppRouter
      actionQueue={actionQueue}
      globalErrorComponentAndStyles={initialRSCPayload.G}
      assetPrefix={initialRSCPayload.p}
  />
</ServerRoot>

Next.js adds a component to your component tree, above the AppRouter called ServerRoot. From there it streams to AppRouter the RSC Payload data.

Ultimately that data is streamed to React's Promise-based APIs for accepting the Flight format.

Thus React provides APIs for building its Virtual DOM from the Payload, and Next.js (or any RSC-supporting meta-framework) has its own mechanisms for getting that data to React after components execute on the server.

Out-of-Order Streaming

There's more to the streaming story though. Different components may complete executing at different times. As Payload chunks stream in, how does React know where in the Virtual DOM (and thus the DOM) to place them?

If we look at the DOM again where we use our DelayedMessage component, it looks like this at first:

<main>
  <h1>understandingreact.com</h1>
  <!--$?-->
  <template id="B:0"></template>
  <p>Loading...</p>
  <!--/$-->
</main>

React leaves placeholders like template with a special ID and HTML comments to note where content should be dropped once the Promise Suspense is waiting for resolves.

The fallback is in the DOM, but when the Promise resolves some new JavaScript is streamed to the page:

$RC = function(b, c, e) {
  c = document.getElementById(c);
  c.parentNode.removeChild(c);
  var a = document.getElementById(b);
  if (a) {
      b = a.previousSibling;
      if (e)
          b.data = "$!",
          a.setAttribute("data-dgst", e);
      else {
          e = b.parentNode;
          a = b.nextSibling;
          var f = 0;
          do {
              if (a && 8 === a.nodeType) {
                  var d = a.data;
                  if ("/$" === d)
                      if (0 === f)
                          break;
                      else
                          f--;
                  else
                      "$" !== d && "$?" !== d && "$!" !== d || f++
              }
              d = a.nextSibling;
              e.removeChild(a);
              a = d
          } while (a);
          for (; c.firstChild; )
              e.insertBefore(c.firstChild, a);
          b.data = "$"
      }
      b._reactRetry && b._reactRetry()
  }
}
;
$RC("B:0", "S:0")

This code inserts the new pieces of the DOM created after the Promise resolves in the right place, where the placeholder was left, and removes the placeholder and fallback.

After this DOM manipulation code is run, the DOM looks like this:

<main>
  <h1>understandingreact.com</h1>
  <!--$-->
  <p>This message was loaded after a 5 second delay!</p>
  <!--/$-->
</main>

This is called out-of-order streaming and simply means taking what is streamed in and inserting it in the right, expected place in the Virtual DOM/DOM tree, even if its expected spot is before other components that finish first.

In this way if one particular component takes longer than others to execute, you don't have to wait for it to update the UI with the results of other components.

So far, however, we've only been concerning ourselves with Server Components. What about the components devs have been writing for years? What about Client Components, functions that execute in the browser?

The answer introduces an unsung hero in the RSC story: bundlers.

Bundlers and Interleaving

One of React's core tenets has always been component composition. You can split the work of deciding what the DOM should look like across many functions, and compose (that is, combine) that work together by having components be children of each other.

For RSCs to not be a dramatic shift of this core tenet, you need to be able to interleave (or weave) Server and Client Components. Client Components need to be able to be children of Server Components. That includes being able to pass props (function arguments).

What that really means is that in your component hierarchy some of your functions will run on the server and some on the client. In the end though, they all will be doing work that calculates how the part of the DOM that they generate should be structured and what it should contain.

It is the responsibility of the meta-frameworks and bundlers to make this happen, and they do. But remember abstractions have a cost. Often that cost is special rules you have to learn to use the abstraction. In this case, abstracting away some of the separation of server and client means following rules to prevent breaking the limitations of the abstraction.

In the case of RSCs there are 3 interleaving scenarios to consider. The rules are, really, about what can be imported by the component depending on where it will execute. They are rules based on how RSCs work along with the bundlers who analyze the directives and imports and pull it all together.

Client Components Imported Into Server Components

This is allowed. It makes sense that this is fine. Bundlers look at import statements to decide which code to include in their bundles, and which code will be downloaded by the client.

RSCs also participate in building the Virtual DOM. They can reference Client Components in their trees, because that Client Component code will be made available to the browser in the bundle.

Let's try adding a stateful Counter to our React course enrollment page:

// components/Counter.js
'use client';
import { useState } from 'react';

export default function Counter() {
    const [count, setCount] = useState(0);

    return (
        <section>
            <p>{count}</p>
            <button onClick={() => setCount(count + 1)}>
                Enroll
            </button>
        </section>
    );
}

// page.js
import Counter from "./components/Counter";
import DelayedMessage from "./components/DelayedMessage";
import { Suspense } from "react";

export default function Home() {
  return (
    <main>
      <h1>understandingreact.com</h1>
      <Counter />
      <Suspense fallback={<p>Loading...</p>}>
        <DelayedMessage />
      </Suspense>
    </main>
  );
}

Notice the use client directive at the top of the file. This is not a React feature. It's an agreed upon convention for devs to mark that a portion of the component tree is meant to be executed on the client.

That component and any components it imports will be bundled as Client Components.

The bundler will note the use client directive and include that component's code (and any it imports) in what is downloaded by the browser.

The Home and DelayedMessage RSCs will execute on the server, and their code won't be included in the bundle. The Payload from the server will look like this:

{
  "type": "main",
  "key": null,
  "props": {
   "children": [
    {
     "type": "h1",
     "key": null,
     "props": {
      "children": "understandingreact.com"
     }
    },
    {
     "type": {
      "$$type": "reference",
      "id": "d",
      "identifier": "L",
      "type": "Lazy node"
     },
     "key": null,
     "props": {}
    },
    {
     "type": {
      "$$type": "reference",
      "id": "e",
      "identifier": "",
      "type": "Reference"
     },
     "key": null,
     "props": {
      "fallback": {
       "type": "p",
       "key": null,
       "props": {
        "children": "Loading..."
       }
      },
      "children": {
       "$$type": "reference",
       "id": "f",
       "identifier": "L",
       "type": "Lazy node"
      }
     }
    }
   ]
  }
}

Notice there's a new "Lazy node" reference where the Client Component will be. That part of the Virtual DOM will be known when that Client Component executes. That will happen either when the Client Component is SSR'd (if the framework does that) or when it executes in the browser.

One more note: if you pass props from a Server Component to a Client Component, those props need to be serializable by React.

As we've seen, the props will be part of the Payload sent over the network. That means anything passed needs to be representable as a string, so it can be converted back into an object in memory on the client.

Server Components Imported Into Client Components

This isn't allowed. You can't import a component that is intended to run on the server into your component that will run in the browser.

Why? Because bundlers shouldn't send RSC functions to the client, only the Payload. Therefore there is no code to import. The bundler won't include the code for the client to download, so the RSC code isn't there to use.

It is possible to import a shared component that is viable to run on both the server and client. But if you import a shared component into a Client Component then its code will be bundled for download by the client. If you import a shared component into a Server Component, then it won't be bundled.

You might thinking: "what if I accidentally import a Server Component, how does the bundler know I don't mean to?"

Good question! This is a bit of a security problem. You could have code in a Server Component that is never meant to be downloaded and seen by others, but you accidentally import it into a Client Component and so it gets bundled in. If it has server-specific features (like connecting to a database) it will fail to execute in the browser, but if it made it into production you might have leaked some sensitive information like the address of your database.

Next.js tries to resolve this by allowing you to mark components as server only. This is a bit like tying string to your finger to remember something though. It's possible to forget to tie the string.

Other meta-frameworks are looking at safer alternatives for ensuring your server code doesn't get bundled and sent to the client.

However, once you accept an abstraction over the server-client boundary, you accept a degree of risk in forgetting those boundaries exist.

Server Components Passed as Children to Client Components

This is allowed. This is a special, interesting case. You can pass Server Components as children props to a Client Component, which is different from importing it.

If we gave our Counter function some children:

// components/Counter.js
'use client';
import { useState } from 'react';

export default function Counter({ children }) {
    const [count, setCount] = useState(0);

    return (
        <section>
            <p>{count}</p>
            <button onClick={() => setCount(count + 1)}>
                Enroll
            </button>
            { children }
        </section>
    );
}

// page.js
import Counter from "./components/Counter";
import DelayedMessage from "./components/DelayedMessage";
import { Suspense } from "react";

export default function Home() {
  return (
    <main>
      <h1>understandingreact.com</h1>
      <Counter>
        <p>Server Text</p>
      </Counter>
      <Suspense fallback={<p>Loading...</p>}>
        <DelayedMessage />
      </Suspense>
    </main>
  );
}

It works just fine, even though the Counter function executes on the client, and the children passed to it (<p>Server Text</p>) were processed on the server!

Why does this work? Because what you're really passing is a portion of the Virtual DOM tree (the results of executing the code), not the Server Component code to be executed.

The Payload looks like this:

{
   "children": [
    {
     "type": "h1",
     "key": null,
     "props": {
      "children": "understandingreact.com"
     }
    },
    {
     "type": {
      "$$type": "reference",
      "id": "d",
      "identifier": "L",
      "type": "Lazy node"
     },
     "key": null,
     "props": {
      "children": {
       "type": "p",
       "key": null,
       "props": {
        "children": "Server Text"
       }
      }
     }
    },
    {
     "type": {
      "$$type": "reference",
      "id": "e",
      "identifier": "",
      "type": "Reference"
     },
     "key": null,
     "props": {
      "fallback": {
       "type": "p",
       "key": null,
       "props": {
        "children": "Loading..."
       }
      },
      "children": {
       "$$type": "reference",
       "id": "f",
       "identifier": "L",
       "type": "Lazy node"
      }
     }
    }
   ]
  }
 }

Notice the "Server Text" portion of the Payload. It's already passed as a prop to the Client Component. It's as if you'd simply written the JSX in the Payload directly in your Client Component.

Bundlers: The Unsung Heroes

All of this serves to show an important point. React Server Components, in many ways, are a bundler feature.

The bundler analyzes your code, and ensures that Client Components are in the bundle and helps ensure references to those Client Components appear properly in the Payload.

Bundlers are a first-class citizen in React. If you look at the React codebase you'll find folders like:

/react-server-dom-parcel
/react-server-dom-turbopack
/react-server-dom-webpack
//...and more

Inside those folders are code having to do with Flight, helping the bundled code get all of this right.

Because bundlers are the unsung hero of RSCs, it also means that other conventions are possible. A meta-framework doesn't have to buy-in to the use client approach that Next.js uses. TanStack Start, for example, is implementing RSCs simply as functions that "return JSX" (i.e. the Flight format).

React has provided an API: streaming Flight data. It's up the meta-frameworks to iterate and innovate on how they use that API.

Hooks and RSCs

Execution on the server comes with some advantages, but also some limitations.

React doesn't just store the structure of elements in the Virtual DOM, it stores state. When you write:

const [counter, setCounter] = useState(0);

in a component, it places that data in a node on a linked list attached to your component's place in the Virtual DOM. In reality, then, that state is sitting in a JavaScript object in the client browser's memory.

So, React Server Components, by their very nature, can't use those hooks. They run in the wrong environment to do that.

That means, ultimately, that RSCs are non-interactive. Interactivity in React generally means triggering a client-side React re-render, and that happens by updating state.

This means that as your app gains more and more interactive functionality, you tend to refactor your Server Components into Client and Server Component compositions.

Whenever you need something like useReducer or useState, you need a Client Component.

If you keep in mind where your components are executing, you'll use (or not use) Hooks properly.

To Hydrate or Not to Hydrate

I wanted to mention for a moment a point of common confusion. Do RSCs hydrate?

The answer is no. Hydration is about re-executing the actual functions on the client, in order to build the Virtual DOM so that events can be hooked to their handlers.

In React, when we click a button, that event is sent way up the DOM tree to React's root, where React then determines which component should handle the click (the answer is the component that was responsible for creating the button).

Thus you need the Virtual DOM in place and the code that handles the click so that React can respond properly to the event.

RSCs are non-interactive. They won't set state, they won't handle clicks, at least not via React's normal approach. Their code isn't sent to the client for execution, so by definition they don't hydrate.

However, they are part of building the Virtual DOM. They are part of tree reconciliation. The fact that they don't hydrate doesn't mean they aren't in the tree during hydration. They are.

Refetching and Reconciliation

In real world apps you likely are not not just concerned with the initial load of a page, but concerned with refetching those server components.

That means asking the server to re-execute those components (perhaps with new props), and provide new Payload data to update the Virtual DOM with.

For example, if we are paginating through a list of data, and that list is generated by an RSC, we want to get a different set of data if the route is /page/1 versus /page/2.

This is an advantage of RSCs, and most likely integrated with the meta-frameworks' router. The meta-framework doesn't have to do a full page refresh, even though the UI is calculated on the server.

By its very nature, RSCs can stream Virtual DOM definitions to the client, and React can then perform client-side reconciliation as normal. In other words, the page doesn't have to refresh and you don't lose other state on the page.

In this aspect RSCs can provide the best of both rendering worlds. They can run on the server, but update as if they were executed on the client.

Now that we've covered how RSCs really work, this hopefully makes more intuitive sense. React already updates the DOM by diffing the Virtual DOM. So if we can get Virtual DOM data from the server, it can do what it always has.

The Bundle Size Confusion

For over a decade now, I've pushed having deep understanding how the tools you use work. That's what my courses have always been about.

I'm happy that so many students have appreciated that approach. Yet, every now and again, someone complains "too much theory, just learn by doing".

One of the major values, however, of understanding how the tools, libraries, and frameworks we use work is we can make good, informed architectural decisions.

For example, there's been confusion in the Next.js world on the benefits of RSCs. There's a pretty extraordinary discussion on the next.js code repository about the __next_f() function.

Devs who started to use RSCs discovered that there was duplicated data being passed to this function in script tags at the bottom of their pages. Some asked why it was there and if it could be turned off.

What is this doubled data? You guessed it. The Payload! Those function calls that were streamed in ultimately pass that Payload data to React to create the Virtual DOM. This is shocking if you don't understand how all this works.

The issue is that it increases bandwidth usage, which many were complaining about. You're sending more data across the network.

Why were people surprised? Well, Vercel originally described RSCs this way on Next.js' documentation site:

The phrase "the client down not have download, parse, and execute any JavaScript for Server Components" was the misleading one. It isn't really true. Vercel was referring to the actual JavaScript code of the Server Components, but they used the word any.

I had an interesting branching conversation with them on social media. I like to think that was part of the reason the wording was later changed (kudos to Vercel for changing it):

The new description says that Server Components "can reduce the amount of client-side JavaScript needed". This is true! But they can also increase it, because the Payload, in a sense, is JavaScript, or at least data passed to JavaScript functions.

The core misunderstanding of devs is that bundle size and bandwidth usage are not the same thing.

Server Component code is not in the bundle! So they do reduce bundle size! But the Payload is doubled data, and if that data is large (like a big blog post like this one) you'll end up sending more bytes than you save.

When Should You Use RSCs?

So, when should you use RSCs? The right answer, as always, is "it depends". Being armed with an accurate mental model of how they work will help you make that architectural choice.

For my part, I wouldn't use RSCs for a big blog post like this one. The bandwidth usage doesn't make sense to me. I'd use something like Astro for content-heavy sites and apps.

On the other hand, if I had a lot of DB access and complex logic, I might offload that to the server by doing it on a Server Component. The same if I needed to use large JavaScript libraries to produce a relatively small amount of content. If the bundle to Payload trade off is worth it, RSCs make sense to me.

If I have a highly interactive app, and I'm iterating and constantly adding features, I'd also be hesistant to do too much client/server refactoring and might keep it as mostly Client Components.

There are simply too many variables to make a hard recommendation. The best I can do is what I tried to do here in this post: help you understand, so you can come to an informed decision.

Looking Forward

What's the future of React Server Components? It isn't entirely clear. React has made the API, and meta-frameworks are using it.

I think the TanStack Start approach of functions that return Virtual DOM, rather than full Server Components, will be popular. But for some uses, Next.js' approach will work well.

I hope to see incremental improvements in security and performance. For example, if a branch of the Virtual DOM is all Server Components, some reconciliation or hydration optimizations could be made to skip that part of the tree.

Diving Deeper

I hope you found this post useful to your understanding of React Server Components. For a deep dive like this into all of React, from scratch, you can enroll in my full course Understanding React.

Over 27 modules and 16.5 hours of video content we dive into React's source code together, to build the most valuable tool in a developer's toolbelt: an accurate mental model.

Happy coding!

Normal UI: A Usability Technique For Non-Designers

2024-09-02T00:00:00Z

Normal UI: A Usability Technique For Non-Designers

I've been building web apps for 25 years. B2B, SaaS, eCommerce, intranet apps, and more. I've also been a UX designer for much of that time. I've run and watched hundreds, if not thousands, of usability tests.

That means I've been watching average users (non-developers) try to use web apps (without helping them) for over two decades.

You begin to see patterns in what makes a web app usable or unusuable under particular circumstances.

In this post I will introduce you to a technique that I developed over those years. It provides a simple, concrete framework to improve web app usability, is friendly to non-designers, often results in cleaner code and improved accessibility, and facilitates good UX and developer communication.

I call it "Normal UI".

(If you'd like to watch a video version of this post, I'm embedding it below.)

The Design Dilemma

There are two versions of a dilemma in web app design that I see devs dealing with:

They don't have a designer to work with.
They have a designer to work with, but "design" only means visual appearance.

The first case is often true with very small dev teams. Dev teams use UI component libraries, purchase templates, and do they best they can.

I've seen the second case quite often as well. Many web designers come from the graphic arts, and moved to web design to find employment. As a result their expertise lies in visual appearance (which is important), but not usability.

Sometimes the dev team prevents the designer from expanding their role. The designer may want to make usability recommendations, but the dev team only sees a designer's role as making what they build look pretty.

These situations are common. In both cases, the dev team lacks usability expertise.

I call this a "dilemma" because, these days, successful web apps are usable web apps.

Years ago, when people found an app hard to use they would blame themselves. They were always wrong. It was always the design. But, thankfully, times have changed.

Users, customers, clients, and stakeholders want a good user experience. When your app has good usability, you end up with more paying customers, happy users, and satisfied stakeholders.

In the 21st century, you need the web apps you build to have good usability. But here's the hard truth: using a UI component library or template does not guarantee that your web app has good usability.

You can have a brilliantly coded and beautiful button, but that doesn't matter if the user doesn't notice the button or if the words on the button don't make sense to the user.

Using a UI component library or template does not guarantee that your web app has good usability.

A straightforward way to think about usability is to think of a task in your web app. What are the series of action (usually clicks or taps or typing) a user has to take in your web app to accomplish that task?

At each step, the user has to out 1) figure out what action to take and 2) mentally process what is on the screen after they take that action. A fundamental aspect of good usability is ensuring that both of these steps are clear and understandable at every moment from starting to try and accomplish the task through to completing it.

We'll call this sequence of actions a user flow or workflow.

Getting this right is crucial to successful web apps. A beautiful app that's confusing or frustrating to use will not be successful.

But being able to consistently build usable workflows is a skill that must be cultivated.

I have found, however, that there is a simple framework to make workflow design decisions that consistently improves the usability of web apps. By "improves usability" I don't mean subjectively. I mean when formally tested with real world users, the results improve dramatically.

Normalization

Over the years as a dev, I've discovered that a useful metaphor for thinking through workflows (I won't use the term "user flow" any more, since in Normal UI I use a specialized simplistic kind of user flow I just call a "workflow") is database normalization.

A simplistic way to describe the concept of database normalization is that a table (or relation) that is normalized is more focused on a particular thing, and a denormalized table was less focused.

A normalized table of orders may contain an order date, but only an ID of the customer. A denormalized table may contain the order date and all the individual customer data.

The denormalized table is faster to get information from, but there is greater information density and therefore requires more mental effort to read through and find what you're looking for.

The same is true for workflows. A screen (that is a page or modal) has a finite amount of controls and information on it. Thus we say the more screens you visit from the beginning to the end of the task the more normalized that workflow is.

If you carry out various actions but stay on one or few screens we'll say that workflow is denormalized.

This is the core of Normal UI. You take tasks in your software, and decide between designing "normalized" workflows or "denormalized" workflows to accomplish that task. That is, you decide if the user mostly stays on one screen, or if actions take them across various screens.

Normalized workflows reduce cognitive load at each point, meaning how much the user has to take in and think about. Denormalized screens, on the other hand, can be more efficient for practiced users to accomplish tasks quickly.

You can draw these workflows. I draw squares to represent screens, circles to represent states of a screen (which I call "frames"), and arrows to represent actions the user takes.

When you draw a workflow, if you have few squares and lots of circles it shows the user stays on just a few screens while working, and thus the workflow is denormalized.

If, instead, you have lots of squares and few circles, that means the user is moving across various screens while working to accomplish the task. Thus that workflow would be considered normalized.

Denormalized workflow on the left, normalized workflow on the right.

I say that you don't have to be a designer to use Normal UI. If you can draw circles, squares, and arrows, you can make some very important, impactful usability design decisions.

The concept of interface normalization gives you the framework you need.

A Concrete Example: Dangerous Workflows

With the notion of normalized versus denormalized workflows, I have found that you can make concrete recommendations on which to use when.

For example: dangerous workflows should be normalized.

What I call a "dangerous" workflow is something mission critical. A task the user performs that results in something impactful that cannot easily be undone.

A common example is sending a mass email. The sequence of clicks the user takes in your app to send a mass email is a "dangerous workflow".

By normalizing the workflow, we slow the user down, make the action more explicit, hand-hold them through where they might make mistakes, and ensure they understand the impact of what they are about to do.

For example we might have an invoice screen where you can click a button and send an email to customers who owe money on their invoices:

Clicking 'Send Payment Reminder' is the beginning of a dangerous workflow.

Once the user carries out this action it cannot be undone. You might have a confirmation popup after clicking the button, but after awhile users tend to blow through those without reading them.

If we were to draw the workflow diagram, it might look like this:

The user stays on one screen, with two states: a confirmation popup and a confirmation toast.

The user stays on one screen during the entire task. The workflow is highly denormalized. But, since it's a dangerous workflow, we normalize it.

We spread the work across multiple screens. For example, after clicking the button they might instead come to a screen that looks like this:

By normalizing we give each screen greater focus on a particular action.

If we were to draw the workflow diagram for the normalized version, it might look like this:

The user moves across multiple screens to accomplish the task: the invoices page, a sending page, and a confirmation page.

There are now more squares than circles. More screens than states.

We lower cognitive load and information density by normalizing the workflow onto multiple screens. In this case, on a new screen we can get the user's attention and focus them on the full impact of what they're about to do.

We can also make it easier to stop themselves from carrying out the action if they realize that isn't what they want to do.

We also give ourselves room to grow for new features, as software scope tends to grow over time.

But normalized interfaces aren't always better! In some cases denormalized workflows improve the practiced user's experience.

For example, if we were to add complex filtering to the invoices page, we may want a button to open the filters and show the filters on that same page. So filtering would be a denormalized workflow.

Some simple metrics, like how often the user uses the workflow (i.e. frequency-of-use) help define when to normalize and when not to.

Technical Benefits

I've also found there are technical benefits to thinking in these terms.

App Skeleton

A workflow diagram directly translates to the app skeleton. If you're using a JavaScript framework to build your app, then screens equate to routes (and sometimes modals) and states of the screen (the circles in the diagrams) relate to information being shown or hidden in a particular template.

Normalized workflows generally result in more, smaller route components, while denormalized workflows result in fewer routes but more components per route.

Accessibility

Native controls (i.e. those that are built into the browser) tend to be more accessible. When you normalize a workflow across screens, I have found you tend to use more native controls and less custom-built controls.

This is because you have the screen space to build straightforward UIs for complex UI cases that otherwise would have to be somehow squeezed onto busy pages.

Performance

Your workflow diagram also defines what can be lazy loaded in your application.

Whatever appears in the circles on your diagram, can be moved onto a lazy-loaded component. Squares are routes that can also be lazy loaded.

If you find a particular part of a workflow task is a performance hit, you can normalize it onto its own screen or screens.

This becomes even more true with a framework like Qwik, which automatically separates and lazy loads responses to clicks and taps (the actions in the workflow).

Thinking in terms of normalized and denormalized workflows doesn't just improve usability, but gives a way for devs and designers to talk about performance, file structures, clarity, cognitive load, bundle size, and efficiency.

The Book and Video Series

There's a lot more to share, but I hope you found this introduction to Normal UI useful.

I've considered writing a book on this subject for years. I have an old blog post from 2014 where I started, but never posted it.

After another decade of successful use of the Normal UI technique, I decided it was worth putting out into the world for dev teams to use. So, I wrote a book.

You can find the book at normalui.com. You also can bundle the book with the video series where I walk through using the technique to improve the usability of common web app features, as well as how to prompt an AI to implement Normal UI.

The book is a fast read, so you can start implementing Normal UI right away.

You can download the first 4 chapters free here.

Easier-to-use vs. Easy-to-use

Normal UI is about making your web apps easier to use. It doesn't replace usability and user experience expertise. It certainly doesn't replace usability testing and other forms of user research.

What it does do is give you a foundation that will result in strong usability improvements.

You'll have a way of talking about and thinking through your software that puts you in the mindset of your user and yields benefits by following a framework, instead of subjective opinion, which is what design discussions sometimes devolve into at dev shops.

An AI-friendly Approach

A funny thing happened shortly after releasing Normal UI as a technique. The AI explosion changed the coding landscape.

As it turns out, Normal UI works wonderfully in conjunction with generative AI. You can teach an LLM the Normal UI approach and terminology, and it gives you a vocabulary to guide an AI during UI generation.

I've found that it greatly improves the experience and output of iterating with an AI on a workflow. In the video series I give you a prompt to get you started.

Successful Web Apps Are Usable Web Apps

I hope this technique helps you build successful, usable web apps.

For myself, it's the culmination of 25 years of working in both dev and UX. The two disciplines are complimentary, more so than most dev shops even realize.

With the right frame of mind, and the right tools, you can reduce user frustration, user error, and design and technical debt.

Think normally.

How to Rewrite a Web Application

2024-07-29T00:00:00Z

How to Rewrite a Web Application

You're about to start rewriting a web application. If your first step is to choose your technology stack and start estimating features: STOP, you're doing it wrong.

A screen-for-screen, feature-for-feature rewrite is a massive waste of opportunity and a huge waste of time and money.

Let's talk about how to do it properly.

The Big Lie

The big lie of software rewrites is: "the requirements are already there in the existing software". If you think that, you're lying to yourself.

That's like saying "the previous process that resulted in this software was perfect". No, it wasn't. I've seen so many teams get themselves in trouble by starting with this mindset.

Assume the existing software is full of requirements holes and unneeded fluff.

The old app is an unkept garden. There are flowers there, for sure, but you need to pull the weeds.

The Port Problem

When your plan is to do a "tech lift" or "port" of the existing software (that is, a screen-for-screen, feature-for-feature rewrite) you aren't just porting the features.

You're also porting, at the very least:

The old design choices based on the tech limitations of the time.
The previous assumptions that are now known to be false.
The custom-built features that could now be handled by 3rd-party utilities.
The lack of knowledge from when the app was originally built (like how the users will use the software in real life).
Security and business rule holes that management hasn't realized exist.
The old technical and design debt from the requirements, UX, and coding decisions made at the time.

What's The Better Approach?

A proper rewrite of an existing application is not first a technical project. It starts its life as a research project.

But it's an incredibly low-cost research project, because all the years of testing have already been done. The existing software and its users are a gold mine.

A research-based rewrite saves time, money, and frustration. All you have to do is take advantage of all that existing test data.

The Cow Paths

In terms of software, the "cow path" is the workflow that users adopt to accomplish their work, when that workflow isn't explicitly implemented in the software.

I once worked a software rewrite where there was an invoicing feature that had a throwaway "notes" field to add open text notes to an invoice. Users used that field for all sorts of things. In the end the years of data in those notes fields were a massively useful (and, for the stakeholder, terrifying) research result that drove new requirements.

Whether through user interviews, user observation, data analysis, or analytics the existing software may contain a treasure trove of workarounds. Once you know how the users need to work, you can make that path the easy path in the new software. You may also realize what you need to prevent users from doing.

The great thing is, none of this is guesswork. The answers are right in front of you in the old software.

Research how the old software is used. Then, in the new software, pave the cow paths.

The Why Down

I've written before about the process I use to create the best outcomes for software development. I call it "the why down".

At its core, it's about finding the problems that need to be solved and determining the least amount of software needed to solve those problems.

As it turns out, the same mindset works fantastically to produce a successful software rewrite. Take any feature in the old software (and all the implementation details under-the-hood), and:

Ask "why" until you arrive at the original problem the feature is solving.
Determine if the old problem still exists.
Determine if the old feature is still the best way to solve the problem.
Determine if this or other features also solve any other original problems, and consolidate what features are really needed.

In other words, the new software needs to solve the set of problems the old software solves. That doesn't mean it needs all the same features.

The Design

There is an extremely valuable piece of design data you can extract from the old software and its users: how often do people follow a particular workflow?

The more often users use a particular set of features, the more they can be designed for "power users". You can make often-used features more dense, with more options grouped on one screen.

The less often users use a particular set of features, the more they can be designed for hand-holding. You can make infrequently-used features less dense, spread across more screens with less options. That way you can make each step of the workflow as clear as possible.

Why? Cognitive load. The less users use a feature the harder it is for them to remember how to use it. On the other hand, users who use features very often can develop cognitive muscle memory and don't have to rely on documentation.

Less-used features are tailored for ease-of-use, and more-used features are tailored for speed-of-use.

The same is true for the complexity and usability of all features. If something is hard to use in the old software, there are two possibilities: you don't need that feature after all, or it can made easier-to-use.

People will already struggle with new software, even if it supposedly matches the original. Give users something more thoughtful and usable than what they had before and you build a lot of goodwill which comes in handy when bugs crop up in new systems.

Your designers can (and should) take into account what can be gleaned from the old app to make the rewritten app even more usable than it otherwise might have been.

The Stack

Choosing a stack for a web application is a daunting task these days. JavaScript frameworks abound. Open-source utilities proliferate. But choosing a stack becomes a much less stressful "let's hope this goes well" experience when you've done the groundwork we've talked about so far.

You may realize that entire swaths of problems that need to be solved (that's a better way of thinking than "features") can be solved with 3rd-party tools and APIs that weren't available when the old software was designed.

I once worked a rewrite where we realized 80% of the code was to support problems that were solved by content management systems and a file sharing API. We integrated two existing 3rd-party tools, and rewrote the other 20% in a stack that we knew would work for the remaining custom design.

Having a clear picture of the needs of whatever features need to be created also helps choose the stack. You know what you need to accomplish, and you can pick your stack accordingly.

Avoiding technical debt and choosing the right stack also depends on your designers making smart choices for a web application. If they go crazy in Figma designing non-standard, non-native controls that all need to be custom built, you are hurting your team and your users. Prefer native controls whenever possible, and use well-tested, accessible UI libraries for everything else. Make custom-built controls earn their way into your apps, if at all.

Stack choice is not all-or-nothing. But to get out of the myopic view of feature re-creation, you need to think in terms of the "why" of a feature, and understand how users use the old app. If you do that, you open up your world of possible solutions, likely saving time, money, and frustration.

The Release(s)

If at all possible, avoid a single release where you completely replace the old web app. Instead, release new features as-you-go to a beta test group of users.

That can be a challenge under some circumstances. I worked a rewrite of software running a large company, where the new system needed an entirely new database.

We still released iteratively, and resolved the data with a combination of automated transfers of data between the old and new systems, as well as utilizing our most agreeable users to do double entry. Double entry also became a way to test for holes in business logic, bugs, and usability issues.

The best result from double entry was that users wanted to switch to the new web app as soon as possible because it was so much easier to use, and resulted in more reliable data.

Don't think of "replacing the app", think "here's the new way to solve the same problem".

Plan releases using the Minimum Solved Problems approach, where each release defines a set of problems that are solved.

When you iteratively release, it's much easier for the designers and devs to handle feedback and problems, and you can pivot when needed.

The Course

Everything we've talked about here can be practiced and learned. You just need to adjust your approach and your dev culture when it comes to rewrites.

If you're working on, or about to work on, a rewrite, and you think your team would benefit from training on how to do this, I include more on all of this in my Udemy course How to Build the Right Software (and Choose the Right Stack).

It dives into everything we've talked about in this blog post and more. Identify the underlying problems, find the best solutions (for you and your users), and choose the right stack to implement it. It includes quizzes, a free PDF worksheet, and I'm in the forums answering questions.

A Rewrite Can Be an Eye-Opening Joy

A rewrite can be a special kind of software project. You aren't blind to what is needed. The existing users and software are a research treasure.

Once you know why each feature exists, and what problems need to be solved, winnowing down the actual features needed is extremely satisfying.

Realizing you don't need as much software as you thought, finding just the right stack choices to ease implementation, and watching users want to use the new app can be a joy.

You just have to approach a rewrite properly.

Smart Jerks Aren't Worth It

2024-07-24T00:00:00Z

Smart Jerks Aren't Worth It

Myths proliferate in every culture. Some are harmless. Some are not. The myth of the "difficult genius" is perhaps one of the most harmful myths that still exist in software development today.

Your software is hurt by toxic personalities on your team. Smart jerks aren't worth it. Let's dispel the myth.

The Myth of the Difficult Genius

The myth of the "difficult genius" is not unique to software development. The myth itself proliferates in part because of famously difficult-to-deal-with scientists, mathematicians, engineers, and more throughout history.

A steady diet of books, movies, and pop culture have taught us that great things are accomplished by jerks and the people who tolerate them. This has been true.

It is also true that great things have been accomplished by well-functioning cohesive teams of people who respected each other. That, however, isn't seen as fodder for great storytelling (who wants to watch or read about a team getting along).

The important question is: which one do you want your software team to resemble?:

"The jerk and those who tolerate them"? Or...
"The cohesive team that accomplishes great things"?

What Is A Jerk?

Communication styles differ for many reasons: cultural, experiential, and physical. The intent here is not to label every person that we come into conflict with as a "jerk".

However, there is such a thing as toxic behavior. In the "difficult genius" tolerated by a dev team, that behavior can often be labeled as "obnoxiously aggressive". I borrow that term from the video that inspired this blog post, delivered by my friend Jamie Smyth from The Smyth Group.

You can find the original video below, and I encourage you to stop right now and watch it. It's only 2 minutes long, but contains so much truth in such a short amount of time. It also gives good examples of what we're talking about when we say someone is acting like a jerk.

Let's define the term "jerk" here as someone who is both intentionally, and obnoxiously aggressive. Aggressive in their enforcement of their own opinions and dismissive of others'. Obnoxious in the frequency of unnecessary negative interactions with them. Intentional in that they understand their behavior is aggressive, and choose not to adjust it.

Ultimately, you know you're dealing with someone who is acting like a jerk by how you feel after interacting with them. If most interactions leave you feeling emotionally exhausted, dismissed, belittled, or angry, you may be dealing with toxic behavior on your team.

Toxic behavior is ruinous both to software and the devs who build it. But it's often excused.

The Excuses

There are various excuses teams give themselves for tolerating toxic behavior. These excuses are wrong.

They're The Only Ones Who...

Sometimes the source of toxicity is also a nexus of legacy information. They're the "only ones" who know how something works, or the only ones with a particular skill.

If that is true, your team is in danger. Good documentation and process should improve everyone's knowledge and reduce dependencies on any single individual.

If they really are "the only ones" then you have a process problem, a symptom of which is tolerance of toxic behavior.

They Produce

Sometimes the source of toxicity produces a lot of code. If this is the excuse we give then we are valuing the wrong things.

A well-functioning, cohesive, happy team can come up with novel solutions, better implementations, and well-reviewed code. Toxic behavior prevents this. Therefore, you are making a bad sacrifice: team output for individual velocity.

Value most what the team as a whole produces and how they feel while they're producing it. You'll likely lose less people to employee churn, which means you'll have a more mature team producing more software in the long run.

They're Logical

No. They're people. They're emotional. The fact that they are inconsiderate of others does not make them more logical.

If someone is obnoxiously aggressive, they are satisfying some sort of emotional need at the expense of others. Maybe it's rooted in ego. Maybe it's rooted in insecurity.

The myth of the "difficult genius" is rooted partially in this false notion of logic over emotion. The smart jerk is showing that they are unable to self-regulate their emotions.

They aren't logical. They're emotionally immature.

They're Brilliant

Smart jerks are often tolerated because they're smart. We like learning from smart people, even if it's just from watching them work.

This is the fundamental benefit of the smart jerk. But if that person's behavior negatively impacts team dynamics, makes people afraid to speak up, and squashes group brainstorming, the cost is simply too high.

There are plenty of brilliant coders in the world. Teams need brilliant coders who are also tolerable to work with. Brilliance gets you in the door, but a dev's impact on team cohesiveness and output decides their long-term outlook.

The Impact

Here is a list of just some of the negative effects of tolerating an aggressively obnoxious coder:

Loss of Ideas: When people are afraid to speak up, great ideas are lost to silence.
Loss of Energy: When team members' emotional energy is used up dealing with toxic behavior, they have less to give to their work, their code, their teammates, the customers and the users.
Loss of Motivation: For a team to do its best work, its members need to want to work. Not wanting to work with a source of toxicity ends up means not wanting to work at all.

Any of these are devastating to a team's output and longevity. Be aware of the costs of tolerating toxic behavior.

Can They Be Helped?

A smart jerk can change their ways. Your team may choose to take whatever steps available to deal with the issue. Whether that's one-on-one with a manager, HR, or some other avenue.

It can also be a matter of training. I have a course on team dynamics and soft skills, which I'll mention later.

It's up to your team on if or how to help the source of toxicity. Good organizations work to improve their members. However, every healthy safe organization also establishes boundaries that cannot be crossed.

Prevention

If you and your team are already dealing with a "difficult genius" (i.e. smart jerk), then dealing with the problem within your organizational structure may end up being necessary. Whether that's trying to help the person to change their behavior, or deciding they aren't a good fit for the team.

Beyond that, you should be interested in prevention. We need to find the right people to work with. Plus we should learn how to best interact with our team members, and ensure that we aren't acting like a jerk!

Finding Brilliant People Who Are Nice to Work With

We all want to work with smart people. They produce good work and we improve as we learn things from them. But, for best results, we also need those people to be nice to work with.

Finding those people is not easy. At times, there is a degree of 'taking a chance'. In other cases it's a matter of recommendations from people you trust. There's also the care involved in your organization's hiring practices.

What I can at least do, is give you a recommendation. The folks at The Smyth Group who made the video referenced earlier are both brilliant and nice to work with.

They build custom software, train or bolt on to your existing dev team, help with hiring, and provide an array of useful dev team advisory services.

Reach out to me at talicea@thesmythgroup.com to get in touch. I'm their director of education.

Not Being a Jerk

We all individually need to learn how to improve team dynamics and work with the people around us, but devs generally aren't given that education. We need to avoid being the jerk ourselves, and learn how to best communicate and interact with our team members, within the unique environment that is a dev team.

Since that education is sorely lacking, I made a course. It's called Team Dynamics and Soft Skills for Developers. I put my 25 years of dev, management, tech education, and interpersonal communication training into it. I think you and your team will find it useful.

Teams Are People

Dev teams are a collection of people. People need dignity and respect. Smart jerks injure that basic need within your team dynamic. They hurt your team and your software.

Help them or decide they aren't a fit for your team. Either way, don't tolerate them.

The benefits of their smarts are outweighed by the cost of their toxicity. They aren't worth it.

Understanding React Compiler

2024-06-19T00:00:00Z

Understanding React Compiler

React's core architecture calls the functions you give it (i.e. your components) over and over. This fact both contributed to its popularity by simplifying its mental model, and created a point of possible performance issues. In general, if your functions do expensive things, then your app will be slow.

Performance tuning, therefore, became a pain point for devs, as they had to manually tell React which functions should be re-run and when. The React team has now provided a tool called the React Compiler to automate that manual work performance tuning for devs, by rewriting their code.

What does React Compiler do to your code? How does it work under-the-hood? Should you use it? Let's dive in.

To gain a complete, accurate mental model of React by deep diving into its internals, check out my new course Understanding React where we dig into React's source code. I've found a deep understanding of React's internals greatly helps even devs with years of React experience.

Compilers, Transpilers, and Optimizers

We hear the terms compiler, transpiler, and optimizer thrown about the modern JavaScript ecosystem. What are they?

Transpilation

A transpiler is a program that analyzes your code and outputs functionally equivalent code in a different programming language, or an adjusted version of your code in the same programming language.

React devs have been using a transpiler for years to convert JSX to the code that is actually run by the JavaScript engine. JSX is essentially shorthand for building trees of nested function calls (which then build trees of nested objects).

Writing nested function calls is cumbersome and error-prone, so JSX makes the developer's life easier, and a transpiler is needed to analyze the JSX and convert it into those function calls.

For example, if you wrote the following React code using JSX:

Note that, for ease of reading, all code in this blog post is intentionally oversimplified.

function App() {
    return <Item item={item} />;
}

function Item({ item }) {
    return (
        <ul>
            <li>{ item.desc }</li>
        </ul>
    )
}

it becomes, after transpilation:

function App() {
  return _jsx(Item, {
    item: item
  });
}

function Item({ item }) {
  return _jsx("ul", {
    children: _jsx("li", {
      children: item.desc
    })
  });
}

This is the code that is actually sent to the browser. Not HTML-like syntax, but nested function calls passing plain JavaScript objects that React calls 'props'.

The result of transpilation shows why you can't use if-statements easily inside JSX. You can't use if-statements inside function calls.

You can quickly generate and examine the output of transpiled JSX using Babel.

Compilation and Optimization

So what's the difference between a transpiler and a compiler? It depends on who you ask, and what their education and experience is. If you come from a computer science background you might have mostly been exposed to compilers as a program that converts the code you write into machine language (the binary code that a processor actually understands).

However, "transpilers" are also called "source-to-source compilers". Optimizers are also called "optimizing compilers". Transpilers and optimizers are types of compilers!

Naming things is hard, so there will be disagreement about what constitutes a transpiler, compiler, or optimizer. The important thing to understand is that transpilers, compilers, and optimizers are programs that take a text file containing your code, analyze it, and produce a new text file of different but functionally equivalent code. They may make your code better, or add abilities that it didn't have before by wrapping bits of your code in calls to other people's code.

Compilers, transpilers, and optimizers are programs that take a text file containing your code, analyze it, and produce different but functionally equivalent code.

That last part is what React Compiler does. It creates code functionally equivalent to what you wrote, but wraps bits of it in calls to code the React folks wrote. In that way, your code is rewritten into something that does what you intended, plus more. We'll see exactly what the "more" is in a bit.

Abstract Syntax Trees

When we say your code is "analyzed", we mean the text of your code is parsed character-by-character and algorithms are run against it to figure out how to adjust it, rewrite it, add features to it, etc. The parsing usually results in an abstract syntax tree (or AST).

While that sounds fancy, it really is just a tree of data that represents your code. It is then easier to analyze the tree, rather than the code you wrote.

For example, let's suppose you have a line in your code that looks like this:

const item = { id: 0, desc: 'Hi' };

the abstract syntax tree for that line of code might end up looking something like this:

{
    type: VariableDeclarator,
    id: {
        type: Identifier,
        name: Item
    },
    init: {
        type: ObjectExpression,
        properties: [
            {
                type: ObjectProperty,
                key: id,
                value: 0
            },
            {
                type: ObjectProperty,
                key: desc,
                value: 'Hi'
            }
        ]
    }
}

The generated data structure describes your code as you wrote it, breaking it down into small defined pieces containing both what type of thing the piece is and any values associated with it. For example desc: 'Hi' is an ObjectProperty with a key called 'desc' and a value of 'Hi'.

This is the mental model you should have when you imagine what is happening to your code in a transpiler/compiler/etc. People wrote a program that takes your code (the text itself), converts it into a data structure, and performs analysis and work on it.

The code that is generated ultimately comes from this AST as well as perhaps some other intermediate languages. You can imagine looping over this data structure and outputting text (new code in the same language or a different one, or adjusting it in some way).

In the case of React Compiler it utilizes both an AST and an intermediate language to generate new React code from the code you write. It's important to remember that React Compiler, like React itself, is just other people's code.

When it comes to compilers, transpilers, optimizers, and the like, don't think of these tools as mysterious black boxes. Think of them as things that you could build, if you had the time.

React's Core Architecture

Before we move on to React Compiler itself, there's a few more concepts we need to have clear.

Remember that we said React's core architecture is both a source of its popularity, but also a potential performance issues? We saw that when you write JSX, you're actually writing nested function calls. But you are giving your functions to React, and it will decide when to call them.

Let's take the beginnings of a React app for dealing with a large list of items. Let's suppose our App function gets some items, and our List function processes and shows them.

function App() {
    // TODO: fetch some items here
    return <List items={items} />;
}

function List({ items }) {
    const pItems = processItems(items);
    const listItems = pItems.map((item) => <li>{ item }</li>);
    return (
        <ul>{ listItems }</ul>
    )
}

Our functions return plain JavaScript objects, like a ul object which contains its children (which here will end up being multiple li objects). Some of these objects like ul and li are built-in to React. Others are the ones we create, like List.

Ultimately, React will build a tree from all these objects called the Fiber tree. Each node in the tree is called a Fiber or Fiber node. The idea of creating our own JavaScript object tree of nodes to describe a UI is called creating a "Virtual DOM".

React actually keeps two branches that can fork out from each node of the tree. One branch is called is of the "current" state of that branch of the tree (which matches the DOM), and the other the "work-in-progress" state of that branch of the tree which matches the tree created from what our functions returned when they were re-run.

React will then compare those two trees to decide what changes need to made to the actual DOM, so that the DOM matches the work-in-progress side of the tree. This process is called "reconciliation".

Master React From The Inside Out

Learn More →

Thus, depending on what other functionality we add to our app, React may choose to call our List function over and over, whenever it thinks the UI might need to be updated. This makes our mental model fairly straightforward. Whenever the UI might need to be updated (for example, in response to a user action like clicking a button), the functions that define the UI will be called again, and React will figure out how to update the actual DOM in the browser to match how our functions say the UI should look.

But if the processItems function is slow, then every call to List will be slow, and our whole app will be slow as we interact with it!

Memoization

A solution in programming to deal with repeated calls to expensive functions is to cache the results of the function. This process is called memoization.

For memoization to work, the function must be "pure". That means that if you pass the same inputs to the function, you always get the same output. If that's true, then you can take the output and store it in a way that it's related to the set of inputs.

The next time you call the expensive function, we can write code to look at the inputs, check the cache to see if we've already run the function with those inputs, and if we have, then grab the stored output from cache rather than calling the function again. No need to call the function again since we know the output will be the same as the last time those inputs were used.

If the processItems function from the previous used implemented memoization it might look something like:

function processItems(items) {
    const memOutput = getItemsOutput(items);
    if (memOutput) {
        return memOutput;
    } else {
        // ...run expensive processing
        saveItemsOutput(items, output);
        return output;
    }
}

We can imagine that the saveItemsOutput function stores an object that saves both items and the associated output from the function. The getItemsOutput will look to see if items is already stored, and if it is we return the related cached output without doing any more work.

For React's architecture of calling functions over and over, memoization becomes a vital technique for helping to keep apps from becoming slow.

Hook Storage

There's one more piece of React's architecture to understand in order to understand React Compiler.

React will look at calling your functions again if the "state" of the app changes, meaning the data that the creation of the UI is dependent on. For example a piece of data might be "showButton" which is true or false, and the UI should show or hide the button based on the value of that data.

React stores state on the client's device. How? Let's take the React app that will render and interact with a list of items. Suppose we will eventually store a selected item, process the items client side for rendering, handle events, and sort the list. Our app might start to look something like below.

function App() {
    // TODO: fetch some items here
    return <List items={items} />;
}

function List({ items }) {
    const [selItem, setSelItem] = useState(null);
    const [itemEvent, dispatcher] = useReducer(reducer, {});
    const [sort, setSort] = useState(0);

    const pItems = processItems(items);
    const listItems = pItems.map((item) => <li>{ item }</li>);
    return (
        <ul>{ listItems }</ul>
    )
}

What is really happening here when the useState and useReducer lines are executed by the JavaScript engine? The node of the Fiber tree created from our List component has some more JavaScript objects attached to it to store our data. Each of those objects is connected to each other in a data structure called a linked list.

By the way, a lot of devs think useState is the core unit of state management in React. But it isn't! It's actually a wrapper for a simple call to useReducer.

So, when you call useState and useReducer, React will attach the state to the Fiber tree that sits around while our app runs. Thus state remains available as our functions keep re-running.

How hooks are stored also explains the "rule of hooks" that you can't call a hook inside a loop or an if-statement. Every time you call a hook, React moves to the next item in the linked list. Thus, the number of times you call hooks must be consistent, or React would sometimes be pointing at the wrong item in the linked list.

Ultimately, hooks are just objects designed to hold data (and functions) in the user's device memory. This is key to understanding what React Compiler really does. But there's more.

Memoization in React

React combines the idea of memoization and its idea of hook storage. You can memoize the results of entire functions you give React that are part of the Fiber Tree (like List), or individual functions you call within them (like processItems).

Where is the cache stored? On the Fiber tree, just like state! For example the useMemo hook stores the inputs and outputs on the node that calls useMemo.

So, React already has the idea of storing the results of expensive functions in linked lists of JavaScript objects that are part of the Fiber Tree. That's great, except for one thing: maintenance.

Memoization in React can be cumbersome, because you have to explicitly tell React what inputs the memoization depends on. Our call to processItems becomes:

const pItems = useMemo(processItems(items), [items]);

The array at the end being the list of 'dependencies', that is the inputs that, if changed, tell React the function should be called again. You have to make sure you get those inputs right, or memoization won't work properly. It becomes a clerical chore to keep up with.

React Compiler

Enter React Compiler. A program that analyzes the text of your React code, and produces new code ready for JSX transpilation. But that new code has some extra things added to it.

Let's look at what React Compiler does to our app in this case. Before compilation it was:

function App() {
    // TODO: fetch some items here
    return <List items={items} />;
}

function List({ items }) {
    const [selItem, setSelItem] = useState(null);
    const [itemEvent, dispatcher] = useReducer(reducer, {});
    const [sort, setSort] = useState(0);

    const pItems = processItems(items);
    const listItems = pItems.map((item) => <li>{ item }</li>);
    return (
        <ul>{ listItems }</ul>
    )
}

after compilation it becomes:

function App() {
  const $ = _c(1);

  let t0;

  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
    t0 = <List items={items} />;
    $[0] = t0;
  } else {
    t0 = $[0];
  }

  return t0;
}

function List(t0) {
  const $ = _c(6);

  const { items } = t0;
  useState(null);
  let t1;

  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
    t1 = {};
    $[0] = t1;
  } else {
    t1 = $[0];
  }

  useReducer(reducer, t1);
  useState(0);
  let t2;

  if ($[1] !== items) {
    const pItems = processItems(items);
    let t3;

    if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
      t3 = (item) => <li>{item}</li>;

      $[3] = t3;
    } else {
      t3 = $[3];
    }

    t2 = pItems.map(t3);
    $[1] = items;
    $[2] = t2;
  } else {
    t2 = $[2];
  }

  const listItems = t2;
  let t3;

  if ($[4] !== listItems) {
    t3 = <ul>{listItems}</ul>;
    $[4] = listItems;
    $[5] = t3;
  } else {
    t3 = $[5];
  }

  return t3;
}

That's a lot! Let's break down a bit of the now rewritten List function to understand it.

It starts off with:

const $ = _c(6);

That _c function (think "c" for "cache") creates an array that's stored using a hook. React Compiler analyzed our Link function and decided, to maximize performance, we need to store six things. When our function is first called, it stores the results of each of those six things in that array.

It's the subsequent calls to our function where we see the cache in action. For example, just looking at the area where we call processItems:

if ($[1] !== items) {
    const pItems = processItems(items);
    let t3;

    if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
        t3 = (item) => <li>{item}</li>;
        $[3] = t3;
    } else {
        t3 = $[3];
    }

    t2 = pItems.map(t3);
    $[1] = items;
    $[2] = t2;
} else {
    t2 = $[2];
}

The entire work around processItems, both calling the function and generating the lis, is wrapped in a check to see if the cache in the second position of the array ($[1]) is the same input as the last time the function was called (the value of items which is passed to List).

If they are equal, then the third position in the cache array ($[2]) is used. That stores the generated list of all the lis when items is mapped over. React Compiler's code says "if you give me the same list of items as the last time you called this function, I will give you the list of lis that I stored in cache the last time".

If the items passed is different, then it calls processItems. Even then, it uses the cache to store what one list item looks like.

if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
    t3 = (item) => <li>{item}</li>;
    $[3] = t3;
} else {
    t3 = $[3];
}

See the t3 = line? Rather than recreating the arrow function that returns the li, it stores the function itself in the fourth position in the cache array ($[3]). This saves the JavaScript engine the work of creating that small function the next time List is called. Since that function never changes, the initial if-statement is basically saying "if this spot in the cache array is empty, cache it, otherwise get it from cache".

In this way, React caches values and memoizes the results of function calls automatically. The code it outputs is functionally equivalent to the code we wrote, but includes code to cache these values, saving performance hits when our functions are called over and over by React.

React Compiler is caching, though, at a more granular level than what a dev typically does with memoization, and is doing so automatically. This means devs don't have to manually manage dependencies, or memoization. They can just write code, and from it React Compiler will generate new code that utilizes caching to make it faster.

It's worth noting that React Compiler is still producing JSX. The code that is actually run is the result of React Compiler after JSX transpilation.

The List function actually run in the JavaScript engine (sent to the browser or on the server) looks like this:

function List(t0) {
  const $ = _c(6);
  const {
    items
  } = t0;
  useState(null);
  let t1;
  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
    t1 = {};
    $[0] = t1;
  } else {
    t1 = $[0];
  }
  useReducer(reducer, t1);
  useState(0);
  let t2;
  if ($[1] !== items) {
    const pItems = processItems(items);
    let t3;
    if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
      t3 = item => _jsx("li", {
        children: item
      });
      $[3] = t3;
    } else {
      t3 = $[3];
    }
    t2 = pItems.map(t3);
    $[1] = items;
    $[2] = t2;
  } else {
    t2 = $[2];
  }
  const listItems = t2;
  let t3;
  if ($[4] !== listItems) {
    t3 = _jsx("ul", {
      children: listItems
    });
    $[4] = listItems;
    $[5] = t3;
  } else {
    t3 = $[5];
  }
  return t3;
}

React Compiler added an array for caching values, and all the needed if-statements to do so. The JSX transpiler converted the JSX into nested function calls. There is a not-insignificant difference between what you wrote and what the JavaScript engine runs. We are trusting other people's code to produce something that matches our original intent.

Trading Processor Cycles for Device Memory

Memoization and caching in general means trading processing for memory. You save on the processor having to execute expensive operations, but you avoid that by using up space to store things in memory.

If you use React Compiler, that means you are saying "store as much as you can" in the device's memory. If the code is running on the user's device in the browser, that's an architectural consideration to keep in mind.

Likely, this won't be a real problem for many React apps. But if you are dealing with large amounts of data in your apps, then device memory usage is something you should at least be aware of and keep an eye on if you use React Compiler once it leaves the experimental stage.

Abstractions and Debugging

Compilation in all its forms amounts to a layer of abstraction between the code you write and the code that is actually being run.

As we saw, in the case of React Compiler, to understand what is actually sent to the browser you need to take your code and run it through React Compiler, and then take that code and run it through a JSX transpiler.

There is a downside to adding layers of abstraction to our code. They can make our code harder to debug. That doesn't mean we shouldn't use them. But you should keep clearly in mind that the code you need to debug isn't just yours, but the code the tool is generating.

What makes a real difference in your ability to debug code generated from an abstraction layer, is to have an accurate mental model of the abstraction. Fully understanding how React Compiler works will give you the ability to debug the code it writes, improving your dev experience and lowering the stress your dev life.

Dive Deeper

If you found this blog post helpful, you might be interested in doing a similar deep dive across all of React's features in my 16.5 hour course Understanding React. You get lifetime access, all source code, and a certificate of completion.

I read every line of React's source code, and then every line of React Compiler's source code. Why? So I could explain React from the internals level, under-the-hood.

React itself is a massive abstraction layer on top of web fundamentals. As is the case with so many abstractions, I find that most devs using React have an inaccurate mental model of how it works, which greatly impacts how they build and debug React-based applications. But you can understand React deeply.

New content on React 19 has been added to the course. Check the course out. You can also watch the first 6 hours of the course for free on my YouTube channel, which I'll put here.

I hope you'll join me on a journey of, not just imitating someone else writing code, but truly understanding what you're doing.

-- Tony

On The Why Down

2023-03-27T00:00:00Z

On The Why Down

How To Do Better Than MVP

How do we build software that solves real problems? How do both software development teams and the organizations that surround and utilize them come together to make good decisions? How do we acknowledge and work with the human factors built into all aspects of software development? How do we know what to build?

The Myth of the MVP

The "Minimum Viable Product" is a great idea on paper. Over the years, however, I find that, no matter the software development process, defining what needs to be built is a problem that it doesn't solve well.

MVP has two major flaws:

The fog of "viability": Who decides what is "viable"? This term is subjective, and highly susceptible to organizational politics and human bias.
The undefined "minimum": Minimum is a moving target, and often incorrect. It's susceptible to siloed organizational structures and communication breakdowns.

MVP isn't the only issue. Companies have adopted Scrum and Agile. These too are meant to approach software in a minimal, iterative, and unifying way. But Agile only produces results as good as the "defining what needs to be built" stage is.

Scopes creep, expectations go unrealized, intended iterations never happen, and people we should have asked are never talked to. While differing in degrees, these are problems that every team, organization, and company I have ever worked for or with have struggled to control. These remained true no matter what software development practices and processes they were using.

Myths proliferate. Buzz words fly. The resulting software is so-so. People are frustrated.

Software Is Human

A massive blind spot in most software development processes is recognizing that it is a fundamentally human endeavor. People are involved, and thus the needs of people must be filled in order to have the greatest success.

People need dignity, agency, and respect.

Dignity: They don't want to feel that they are unneeded, unwanted, or ignored.
Agency: They want to feel they have some control over what they are doing or experiencing.
Respect: They want to feel that others recognize the value of their existing or potential contributions.

You hear the results of these needs not being filled in interpersonal communications, that usually degrade into reduced morale, motivation, cooperation, and productivity:

"Who do you think you are..."
"No one asked me..."
"I can't believe they're making us do this..."

A unified organization produces the best results. Software is cold and calculating. The people that exist in all aspects of software development are not.

Since people are inputs to the software development process, human flaws are as well. People get attached to their ideas, misunderstand, miscommunicate, and filter information through the lenses of their own biases and insecurities.

A successful software development process recognizes these negative aspects of human input, and iterates them away through good process, without tearing people down along the way.

A Better Way

Over my 25 years of software development, straddling and crossing the line between development, UX, and managerial roles, I've seen things go wrong and go right. The popular approaches often go wrong, in both technical, budgetary, and human ways.

What follows is the approach I have had success with in every way. It has worked in both small teams and large organizations implementing Scrum and Agile. It's the way I think software should be developed.

A Seat At The Table

We begin by establishing that everyone has a seat at the table. Everyone involved in the software, be it construction or use, gets input. I call these "seats" at the table.

These are usually representatives from organizational roles coupled with representatives from development roles. Stakeholders, managers, users, designers, developers, security professionals, DevOps, etc. Each role gets a "seat".

This is not "design by committee". The organizational hierarchy still makes the final decisions, and each seat is given due respect and deference for their relative expertise and responsibility. Each seat carries out their own work, using whatever methods are working for them.

In expressing concerns, needs, and constraints, though, they are a team of equals.

Everyone is heard. Everyone is given dignity, agency, and respect. Every seat is a potential source of a good solution that comes from their area of knowledge, experience, and influence. UX doesn't suggest DevOps solutions, they suggest UX solutions to DevOps problems.

Solutions vs. Problems

Next, we establish the fundamental unit of design that everyone works with: the "Problem".

People usually express their problems in the form of solutions. They say, "I need to go to the grocery store", not "I don't have food in my refrigerator for dinner."

This is both natural and highly problematic. Everyone (stakeholders, users, developers, designers, managers, etc.) can become attached to a particular solution, placing blinders on the entire project.

Every role (each "seat") must learn to think in terms of problems, rather than solutions. A "problem" is a statement of needs to be filled or constraints to be respected with no mention of a solution. It does not have to be in the form of a negative.

A designer's "Add a 'Buy Now' button" becomes "Users leave the site before they finish their purchase."
A manager's "Use this template I found" becomes "We want users to find it visually attractive while staying within budget."
A stakeholder's "Output a Word doc" becomes "We need it to be easy to edit."

This process is not just applied to the user experience. It is applied to every seat at the table. Stakeholders, managers, developers, designers, security professionals, DevOps, etc. all distill their solutions, within the context of a particular software project, to problems. These problem statements are shared with all the other seats. This allows solutions to come from anywhere.

For stakeholders and requirements gatherers, this eschews the "gather functional requirements" approach to software development. Don't ask the stakeholders and managers to design the solutions (which is often what gathering requirements degrades into).

Stakeholders and managers are given dignity, agency, and respect by being an active part of the software development lifecycle. The "requirements" are problem statements they provide. They have a seat at the table, and so give what they know but also see what they don't know.

This usually requires cultural change, and can be the biggest hurdle. The "problem" approach needs to be established at the beginning of the project. Frame it positively. Everyone has "full access", a window into all the problems that need solving.

Treat problem statement creation formally as "the process", and treat them as a vital part of it. You may be surprised at how quickly they become invested in doing it right.

The Why Down

What is "the process"? Take the idea of "seats" and "problems", and process them through what I call the "why down".

Every "seat" writes down all of their ideas and concerns. Then, for each idea and concern, they ask "why" and write the answer. If the answer still contains some sort of a specific solution or action, ask "why" again and write the answer. Repeat.

A "why down", then, is the act of reducing (or distilling) a suggested solution to the underlying problem that it is solving. If the solutions are the leaves of a tree, the problems are the roots.

At the bottom of a correct "why down" you arrive at a statement that expresses the problem with no mention of any particular solution or action.

A "why down" might look like this:

"Provide a way to download the report as a Word doc." (Why?)
...so I can edit the report before I send it. (Why?)
...because managers need more information than is in the generated report. (Why?)
...because managers make presentations in higher-level meetings and don't have the information to answer questions. (Why?)

In this way the solution "Provide a way to download the report as a Word doc" becomes a problem statement: "Managers are unfamiliar with the data on the reports".

Note that you can stop asking "why?" as soon as the answer contains only needs/constraints and no actions/solutions. "Edit the report" was an action, and so another "why?" was needed.

If stakeholders/managers have a seat at the table, for example, they may find other solutions to this problem that don't involve software. That's fine. That's the point. We are working to discover what problems exist that software needs to solve. Scope creep is typical in other software development processes. If everyone has a seat at the table, the "why down" often reduces scope.

You may go too far. With each answer, check if you have no actions/solutions. As soon as you don't, stop.

You can give pre-prepared sheets to each "seat" representative(s). Just columns with lines and the word "Why?" on a big arrow on the side pointing down. People usually need training or help at first to do this properly. It's hard to stop thinking about solutions, and express the heart of the problem.

This leads us to a dramatic improvement on the MVP, an idea that emerges naturally from the "why down", and gets everyone at the table on the same page.

Minimum Solved Problems (MSP)

The set of every final problem statement from every seat at the table becomes the "problem space". From that problem space, the minimum required set of problems that must be solved with the current iteration of the software are chosen. This set makes up the "Minimum Solved Problems" or MSP set.

Choose the MSP via whatever organizational hierarchy, responsibility, and determining factors make sense. Everyone has a seat at the table. Not everyone gets to choose which problems are the most important at the moment or which solutions are tried. That's better than an unawareness of other problems, and people not feeling respect nor agency.

This works out fine, because when people feel they were given dignity, agency, and respect, they will often feel ownership of solutions even if they aren't the solutions they suggested. It's easier for them to feel empathy for problems that aren't theirs, and appreciate them being solved, when they know their own problems are on the table as well. The MSP is a team effort.

Each release of the software is an "MSP" release. A release solves the minimum required set of problems in some way, and each problem needs only be solved in one way. Each "seat" implements solutions that fall within their responsibilities using their own best practices.

There are no rules to what constitutes problems, just be sure to specify them. For example, your software will have bugs. Perhaps there are a lot of bugs. It may be decided that a problem is "we want users to be confident in the software". An MSP release may be just a bug fix release. That's great, just make sure you know why (i.e. the problem that was solved).

I find MSP to be superior to MVP in every way. It avoids human biases, attachments, and insecurities. There is no "viability" fog and "minimum" is clearly defined. It results in useful software that solves real problems from day one.

Feature Requests

One of the first things that starts to happen once software is released is feature requests. Most companies take in feature requests and sort them by effort, popularity, etc. That's wrong.

A feature request, by nature, is an expressed solution. So, simply take each feature request and why it down. A feature request is a window into users' problems, not a solution that must be implemented.

Different feature requests often reduce to the same problem statement. Now you can accurately compare the popularity of underlying problems.

"Please add a copy/paste feature" and "We need a 'send via e-mail' button" feature requests may both reduce to one problem statement: "Users can't easily share information."

You can simply add these new problem statements to your User Seat. Feature requests feed into new MSP releases no differently than any other form of user analysis, and the solutions to those problems may be wildly different than the solution presented in the feature request itself.

Solve the underlying problem in only one way. Then release and see what happens. Different feature requests often disappear after one released solution.

Iteration

Software should be developed iteratively, with the understanding that you may never get to the second iteration.

The reality of budgets, time, priorities, staffing, and more can mean good iteration intentions are never realized. That's ok, if the first iteration of the software solves real problems.

If you do get to iterate, the process does not change. Take any new inputs, such as feature requests, organizational priority changes, usability testing results, financial feedback, software bug reports, etc. and why them down into problem statements. Determine your new MSP set. Design one solution for each problem not yet solved. Release software. Repeat.

I find doing this enough begins to change organizational culture. Due to positive business and human results, it becomes a natural, open, and welcome way to solve problems.

You won't just be iterating on the software, you'll be iterating away negative human inputs.

Solving For The Why

Most organizations do not fully understand all aspects of their own processes until they attempt to implement it as software. Most organizations and many dev teams are collections of information silos blocked from intercommunication through poor process or human insecurity. The "why down" and MSP process provides a safe space to tear down walls and bring everyone to the table.

Solving for the "why" leads to the best, fastest, most efficient, and most enjoyable software development I have ever engaged in. I find solving for the why makes people want to come back to work in the morning.

A Welcoming Table

Giving everyone a seat at the table only works if everyone is welcome. Organizational politics, personal agendas, and fear can derail the entire process. Use software development formalized processes as an excuse to get past these problems, but you don't have to say that's what you're doing. Let the process iterate the issues away.

To convince people to come to the table, I find the following arguments work best, depending on the listeners perspective:

This process will save time, budget, and effort.
This process will make sure your concerns, thoughts, and needs are heard and considered.
This process will produce innovation and software that gets the job done.

A welcoming table is one that sees every seat as a potential source of solutions. Engage everyone in the process, and they will feel they had agency and feel ownership over the results, even if their solutions are never implemented.

You will find you have a more unified, happy group of people, who happen to build great software on the why down.

Discuss this with me on Twitter and LinkedIn.

Good Interface, Bad Interface #24

2014-11-20T00:00:00Z

A wall of wine at a winery in Niagara-on-the-Lake. The undersides of the bottles are curved, which gives the wall of wine a lovely reflective appearance.

However the bottoms are curved, not for appearance sake, but to prevent the pressure from bursting the bottles while they sit in the rack.

The best UX is both beautiful and serves a functional purpose. Analyze your design and remove the beauty that exists only for beauty’s sake. Focus on making functional things beautiful.

How To Write Email People Will Read

2014-09-23T00:00:00Z

How To Write Email People Will Read

Email is a part of everyday life. We are inundated. So how do you write an email that clients and co-workers will read?

Give them a good user experience.

UX and Email

People don't just read your email, they experience your email; the flow, the structure, the tone, etc. An email also sits inside of the chrome of the person's email client, webmail, browser chrome, etc. All of these things fight for visual attention.

Thus think of your reader as the user of your email, and concern yourself with their user experience. Scannability, readability, simplicity, gestalt principles and other UX concepts all apply.

Below are some UX tips for writing emails that people will actually read, based on my own experiments and experience.

Short Subject Lines

UX Principle: Scannability

Don't put too much information into the subject line. It's annoying. Huge subject lines suggest that the reader doesn't read email and needs to be beaten to open it. That just makes people want to scan the email and get out, not read it in detail.

Bad example: "Client called and needs update on meeting the deadline now!"

Good example: "Client update needed"

People scan email subject lines. Give a succinct, scannable subject line that explains the email without requiring too much cognitive or emotional processing. They will be more open to reading, not skimming.

Thesis Sentence

UX Principle: Mental Models

Your email should have a thesis sentence; an opening sentence that describes the purpose of and structure of the email. People will scan your email from top to bottom, and a good thesis sentence gives them reason to read and sets the expectation of what they will learn.

Bad example: "We are almost ready on this phase of the project, but we're going to need to talk about some things."

Good example: "I am writing to update you on this phase of the project, and to layout some questions that need to be answered to complete it."

Give the reader a reason to continue reading in detail, as opposed to scanning for what they think is important. You want the reader's mental model of what the email's intent is to match reality.

Verbosity and Adjectives

UX Principle: Simplicity

Do not write like you talk. That's what texting is for. Keep things concise, and do not overuse adjectives. Unnecessarily long sentences, and overused or repeated adjectives will encourage skimming, not reading.

Bad example: "Getting this done is very, very, very important. I just can't overstress enough how important this is - so please, please work on this just as soon as you can."

Good example: "This is our highest priority."

Simple, clearly stated phrases are more likely to be read, recalled, and acted upon.

Emphasis and Calls to Action

UX Principle: Calls to Action

To draw attention to a particular phrase is a delicate balancing act. Draw too much attention and you encourage skimming, not enough and it may be missed.

To draw minor attention use italics.

When calling major attention (such as a 'call to action' - i.e. 'this is something you need to do') use bold. For cases where there are multiple points of emphasis, you may use bold italics for the point of greatest importance. Oh and…

Don't underline. It looks like a link.

Any other form of emphasis will be:

offensive (all caps is yelling)
annoying (multiple font sizes injure readability)
output in an unexpected or less readable way (remember people are reading email on devices of varying size)

Color

UX Principle: Accessibility

Color-dependency is an important usability heuristic. A degree of color-blindness is a common genetic trait in humans. Don't rely on color to get your message across. It is a false emphasizer.

Color also suffers from over-attention. An item of color draws an unequal amount of attention from other forms of emphasis, and can cause skimming or complete skipping of the surrounding black text.

Too much color is just annoying and hurts the eyes.

The lesson: Don't use color in your emails.*

If you can't properly emphasize and call the reader to action with plain text, bold, and italics, you need to rewrite your email.

*exception: your email client may use color when replying to an email inline to distinguish your words from the original email - this is ok, if consistent

Structure, Consistency, and Units of Information

UX Principle: Gestalt

Interface consistency is an important UX concept. The same for email. Don't give your reader (i.e. user) a stream of your current consciousness. Give them a structured set of information, delineated into concise units of information that share the same emphasis and call-to-action styles.

For example, your email may look like this:

Subject line: Concise and scannable

Thesis sentence explaining point of email

Point #1

Details about point 1 with minor emphasis where needed. Here there may also be links, bullet points, questions, and other information.

Call to action: What the reader needs to do or understand

[Repeat the point/call-to-action structure above for each point, question, or subject in your email]

Through consistency and by respecting gestalt principles, you teach the reader how to parse your email. You lower the cognitive requirements for comprehension, and thus increase the likelihood they will read, appreciate, and act. (Note: Be sure to separate details into small paragraphs. A long paragraph may look fine on your desktop, but will be hard to parse on a small device.)

Whitespace

UX Principle: Negative Space

Good use of whitespace (or 'negative space', i.e. the lack of content) in an email allows for easier parsing of information and lowers the probability of a reader missing a piece of information.

As a complement to the structural approach discussed above, separate your headers, calls-to-action, and units of information with whitespace. Also long running paragraphs should be divided into separate paragraphs where each paragraph is a complete thought.

A run-on email is a cognitively exhausting one. Give your words room to breath, and your reader will be able to as well.

Conclusion

Email is an interface. Your reader is the user. Give them a good user experience and they will be more likely to read your email in it's entirety. Reading promotes comprehension. Comprehension promotes appropriate action. Make reading your emails a pleasant experience for your readers. They will be more likely to respond to your emails in a positive, forgiving, and appreciative way.

Remember the UX of email. You just might get read.

One Last Note

If you liked this article, you might like my new course Team Dynamics and Soft Skills for Developers. In it we cover how to communicate with members of your dev team, manage developers, and more.

Good Interface, Bad Interface #23

2014-08-29T00:00:00Z

The diesel fuel pump in one state is green, while in another is black. Quite confusing for the traveler.

One may find oneself confused as to why the pump does not fit into your gas tank…however the prevention of error is extremely important in this case.

Consistency and standards are good things. While making something obvious is the best approach to software design, respecting standards prevents confusion against learned behaviors.

At the same time, preventing error is equally vital, especially if the error will cause serious, irreparable problems.

Good Interface, Bad Interface #22

2014-08-17T00:00:00Z

This gas station pump asks for your zip code when you enter your credit card. Then you have to search around for where to enter it. The keypad is set off to the right and inset.

It doesn’t appear to have any relationship to the screen where the message displays, causing a brief moment of confusion as you scan for an interface to obey the screen commands.

Pay attention to gestalt principles. Elements of an interface that are related should appear to be so visually via position, color, size, borders, whitespace, etc.

Make related elements obviously, visually related, and you will cause less moments of confusion, less scanning, and less frustration.

Good Interface, Bad Interface #21

2014-06-19T00:00:00Z

Boarding a Southwest Airlines plane is a study in frustration. There are always at least several people milling about in confusion, most trying to figure out their line-up process while handling bags and children.

The competitive ‘get on the plane first and claim a seat before everyone else’ turns their confused state into potentials for agitation and aggression (getting ahead of others when you shouldn’t, realizing too late you’re further back than you should have been).

Those who are frequent flyers on the airline have a decided advantage over the new ones, and the agitated state of passengers translate into more frazzled employees.

UX isn’t just about ease of use. It’s about avoiding frustration. It’s about how software makes you feel.

Frustrating software results in agitated users. Agitated users means you have failed UX. Agitated users also introduces a host of other problems, such as exaggerated complaints, lack of patience with other minor software issues, and loss of loyalty.

Care about your users. When they walk away from your software, they should feel good. Or at least, no worse than when they started.

Good Interface, Bad Interface #20

2014-05-25T00:00:00Z

Mall kiosk with a Windows error. Graceful handling of errors is everyone’s job. A poorly handled error can pull the user down into the lower layers of abstraction, destroying the user experience.

Handle errors gracefully, either hiding them, or displaying them as an integrated part of the user experience.

Special integrated error pages or messages go a long way to put the user at ease when an error occurs. It says: “we knew this could happen - don’t panic." This would include user error, coding error, and even OS and network errors where possible.

Assume everything will break - then work up from there.

Simple Is Not the Opposite of Complex

2014-05-22T00:00:00Z

Simple Is Not the Opposite of Complex

My college life was all about education. Mathematics, arts, and sciences were thrown at high speed for high credits. Yet some of the longest lasting lessons didn't come from the classroom - at least not the ones I was paying for. One lesson in particular informed the way I would look at software development and user experience for the rest of my life. It came from pool.

(Life) Lessons in Billiards

I was a commuter in college, and hung out in the 'commuter lounge'. It wasn't very fancy - there were some lockers, a TV, tables and sofas. But the centerpiece of the inner half of the room was the pool table, and it drew me to the place every day.

I fell hard for the game, playing constantly (for better or worse in regards to my GPA). A graduate student saw my love of it, took pity on me, and offered to train me. He was good. Very good. I accepted, and learned a ton.

One day we were watching two students battling in a game full of tough shots. A crowd had formed, cheering as each student holed a particularly difficult bank shot, or combo, or even the occasional felt-ripping masse.

As one student waved his arms, celebrating his hard-fought victory, I mentioned how good the two students were. My billiards mentor said something to me that I'll never forget:

"The guy that makes hard shot after hard shot isn't the one you have to worry about; the guy making easy shot after easy shot is. The guy who always has easy shots knows how to leave the cue ball where he wants - the guy who has to keep making hard shots has no control."

It was so obvious once he said it. The victorious student celebrating in front of me morphed from the best player in the room to the most pitiable. Later, I reduced the thought to:

The best make the problem look easy to solve. The rest celebrate solving the problems they create.

I see this truth again and again, especially in the realm of software. It manifests in software requirements, software architecture, and user experience design. Let's talk about how.

Requirements: What You Need, Not What You Want

How many features does your software need? If you ask anyone who has to pay for software: 'should it do X', the answer is almost always 'Yes'. Ask someone who has to use the software on a daily basis, and the answer may be quite different. Why?

Because those using software (employees) generally are more aware of what is needed, and those paying for software (managers, bosses, owners) are generally more aware of what they want.

Does that mean managers/bosses/owners don't know their companies? At a high level of course they do - but building software highlights the kinds of tiny details that the day-to-day users develop habits to cope with.

I find the best project and product managers help to define software requirements based on needs as seen through existing habit, not wants as seen through RFQs. Users tend to fill holes in process through their own habits. Define how users are already working around a process, and you'll define truly helpful software.

Yet there is such an emotional pull to the idea of just adding features. Giving the number of features priority makes you feel like you're adding value, but really may show that you don't understand the needs. If you truly understand a business or process, you can express its simplest form via the software supporting it.

Deeply understanding the process you intend to digitize is far more valuable than inventing new features. If you understand you can prune away the excess feature wants and get to the heart of habitual feature needs - improving process and filling holes no one but a few on the ground knew was there.

The Best Project Managers: Define a feature set that expresses the patterns of a business or process in simplest form.

The Rest: Add features without stopping to understand if they are really needed or how they will be used. The result is a labyrinth that users will have to navigate, and ultimately will celebrate overcoming through new workaround habits they form.

Coding: Frameworks and Futurists

Why does a coder code? The answer is the same as why an artist paints, or a musician plays. Because they enjoy the act of creation in that medium.

They enjoy solving a problem, and expressing that solution in code that didn't exist before they put their fingers to the keyboard.

Yet that love of the act of creation can cause a coder to be the ruin of a project, or even an entire business. Why? Because 'time is money', and time creating (and then maintaining) comes with a cost.

There are two primary ways in which coders become a weight that drags down the very processes they are trying to support, and they both involve unnecessary complexity: When coders become framework builders and futurists.

The Framework Builder

This is the coder that seems to believe that every problem, no matter how simple, should be solved via a complex code structure (i.e. a framework). They build a layers upon layers of interconnecting code, all to support perhaps the simplest of software.

The problems become apparent quickly. Bugs galore. Difficulty in adding new features or making changes on the fly. Missed deadlines. Budget overruns. But the coder insists they are building it 'the right way' and scoffs at any suggestion otherwise.

Why does the coder insist on unnecessary complexity and then use that complexity to excuse problems?

Note: Sometimes problems really do require complex solutions, but those are the rare cases. Even then, modularity and reusability are not synonymous with layer upon layer of framework code.

Because - the average coder doesn't care all that much about the code he's already written. The code in production is humming away doing its job. Maintenance is a chore, not a joy.

Note: Writing lots of complex code increases the need for maintenance. So, ironically, the love of writing new code leads the coder to spend less time writing it in the long run.

Coders care about the code they're creating right now, at this very moment. That's where they're happy; and creating a full, complex framework keeps them in that emotional space, feeling like they're building something of greater worth than it may actually be.

Framework builders build because they love it. But they create complexity where there is none, possibly hurting others along the way - and his or her emotions keep them from seeing it. In the end the coder who minimizes complexity may be more emotionally mature.

Frameworks should only be as built out as necessary. No more, no less.

The Futurist

Closely connected to the framework builder is the futurist. They too love the act of creation. But their reasoning is not to 'do it the right way' but to do it 'just in case it's needed'.

Code is added to support every possible use case the coder can think of, regardless of being specified by the current software requirements or not. If questioned on it they present it as obviously useful because 'if you need it it will already be there.'

The complexity that handling all those possibilities adds, though, gives either no help or hurts the real needs of the software. It's the coding equivalent of putting wings on a car in case some day the owner wants to fly.

In this case the simplest solution is implementing what is needed, and the complexity comes from trying to predict the future. There is a difference between building a flexible system, and a presumptuous one.

A flexible system makes it easy to add features, and adjust existing ones. It's modular and agile, with clear separation of concerns. However, a presumptuous system is built when the coder assumes that they can think of and handle every possible future situation - even if the business itself isn't planning on it.

We cannot say 'I'm a coder, don't bother me about the business' when asked to consider the business' financial situation while coding…and then the next moment write extra code to handle things 'in case the business needs it.' That's disingenuous.

We're coders. Not futurists. Don't try to handle future scenarios that only you have thought of, even though it's fun. Keep your code real, and enjoy building what's really needed.

The Best Coders: Build flexible, modular systems that provide only the functionality that is needed. Code exists to serve a purpose, not just an emotional need.

The Rest: Build for the love of it, but to the exclusion of reasonableness, creating complexity where none exists.

User Experience: Tasks Expressed as Software

Software is the digital expression of a series of tasks. Even the most complex software can be broken down into distinct, individual tasks because although humans may think about more than one task at a time, that's all they can execute.

That underscores the need for the designer to reduce cognitive load. Humans can only keep so much information in their head. The software should help them focus on one task at a time, and not expect them to remember or learn too much.

Managers and clients, however, will not be thinking along those lines. The pressure and expectations of software development force designers into user experiences that are unnecessarily cluttered and complex.

It Isn't Really That Complicated

The first reaction heard when talking about keeping software simple is: "that works unless the requirements are complex". That reaction is emotional. Either pressure, expectation, or ego is saying to you that the problem is so complex that the software must be as well. But no problem is so complex that it cannot be broken down into simpler problems.

Designers need to push back against the idea that a process is 'complicated' and therefore the software needs twenty buttons and five sortable, filterable grids on every screen. It doesn't. A user won't look at a screen and read all the interface elements - they will hunt for the one element that matches the task that are currently attempting to accomplish.

Don't let deadlines, changing requirements, and feature creep force you into a UX corner. Understand the process you are designing the software to enable; to the degree that you can express it in its simplest forms. If the problem feels too large, break it down into smaller problems and build software that solves those - then link them together.

There is another source of complexity though…and it's one that designers create for ourselves.

It's User Experience Design, Not Just Design

Designers are artists. Much like coders they are designing to create and can get just as caught up in design as coders get caught up in code.

A designer may choose an interface style because it's new and popular, not necessarily because it's the best fit for the job. They may choose a pallet that's fun to work with but a nightmare for a user to stare at for hours a day. They may choose a design that works well in photoshop but is terrible to implement in reality.

Graphics design is not user experience design. It's a subset, but must be tempered by other elements of the discipline: psychology, empathy, and user testing (i.e. humility).

By focusing more on the emotional satisfaction of graphic design, and not on the emotional satisfaction of happy users, we build unnecessary paths of complexity into our designs that may ultimately lead to failure. Then it won't matter…because no one will see our designs anyway.

User experience design can be wonderfully rewarding. But falling for the myth of 'it's complicated', or getting overly caught up in our own creations, can ultimately rob of us of that joy. Keep your designs simple and reasonable. Your users will thank you.

The Best Designers: Understand then reduce a process down to a series of tasks, as granular as reasonable, and express them as software interfaces.

The Rest: Design software interfaces to match the perceived complexity of its creators or their own imagination, but to the users' detriment.

What Is Simple?

In the context of software, simple and complex are not opposites. The lesson of the hard-shot-taking pool player is this:

The opposite of simple is 'poorly controlled'

Poor control of features, poor control of needless architecture, poor control of interface clutter.

Simple is not the opposite of complex. Simple is the distillation of the complex. It's making a seemingly hard problem appear simple through comprehension and skill.

Complexity is easy to create, yet in software discussion, development, and design we celebrate it. Then that complexity is used to excuse the problems the complexity itself creates.

On the other hand, it's hard to be simple. To express something simply you must truly understand it.

Whether it's features that show a firm grasp of process, code that demonstrates restraint, or user experience design that expresses a task naturally; we should all strive for simple.

The simpler, the better.

Good Interface, Bad Interface #19

2014-05-14T00:00:00Z

Simple garage door opener. It does one thing well. There is a single button, and an indicator providing feedback. However it is also extremely easy to click the extruded button.

Time and again I find myself accidentally opening or closing the garage (sometimes with myself in it). So much so that I periodically check that the garage door is closed.

Ease of use is incredibly important in software. However certain functions, especially dangerous ones, should not be made easy to accidentally invoke.

For deletions, take a user to a completely separate screen or large modal with clear indications of what is about to happen.

Wherever possible and applicable, provide ‘undo’, and make it immediately available after the action is taken.

Easy-to-use is rewarding. Easy-to-do-accidentally is frustrating. Be sure your designs know the difference.

Good Interface, Bad Interface #18

2014-03-22T00:00:00Z

Heating and Cooling controller in an older model Kia. There are 12 positions. Seven are labelled. Five are not.

What in the world is the position between ‘defrost’ and 'feet and defrost’? I have no idea. In fact, I still have no idea. Perhaps the designer ran out of room for icons, but the middle states simply aren’t guessable unless you designed the system.

One of the most common mistakes in UX is failing to realize that your design appears usable to you only because you already understand the system.

What is obvious to you is not necessarily obvious to the user. Don’t let love of a design blind you to its failings. Don’t let yourself get away with 'they can read the manual’, 'they should be smart enough to get this’, or other such self-serving thoughts.

Make it obvious. Make it guessable. Make it good.

Key and Lock

2014-03-14T00:00:00Z

Key and Lock

In his seminal work The Design of Everyday Things (revised in 2013), Don Norman notes that with every new technology designers repeat the same mistakes of the past.

User experience designers should not fall into this trap, because a fundamental key to good UX design is humility. It takes humility to change a design based on user testing; and it takes humility to look back at technologies of the past that have endured, and show them their due respect.

One of the oldest and best interfaces has endured for thousands of years. The two part interface: key and lock. Let's pull some software lessons from before there was software.

Guessability

The key and lock is guessable. Most doors have only one keyhole. The key looks like it fits in the hole. If you handed someone a key, and pointed them at its corresponding door, they would likely guess what to do even if they'd never done it before.

Both the key and lock follow DOTW (Do One Thing Well) and it is hard for a user to get it wrong.

Make your interfaces guessable by minimizing ways to get it wrong. Reduce the number of elements in each interface, drawing a clear path to completing any given task.

Security

The key and lock's primary purpose is security. Yet no one complains about it, because it works well and is not hard to use.

You must have the right key, and only the right key for the door to open. It takes special skill to open a door without the key, but no skill to open it otherwise.

Security is important. It should keep things safe. It should just work. It should be trustworthy. Yet when you are authorized, security shouldn't be an impediment to use.

Don't think 'difficult to do' is a valid security paradigm. The people who break security won't be impeded, just your users. Implement good security practices, but simple UI.

Notifications

One reason for the endurance of key and lock is not commonly considered. The key/lock paradigm provides user notifications. Attempts to tamper with a lock invariably leave evidence, like scratches for example.

Users value clear notifications, in security and all other actions. A good notification system can make the emotional difference between feeling cared for, and feeling uncertain and alone.

Consistency

Although generally one key fits in one door, using one key and lock teaches you how to use all of them. No matter the material, appearance, size, country, or epoch, key and lock pretty much works the same way.

Consistency isn't necessarily the most important element of UX. Clarity is arguably more important (consistently confusing isn't good). However, there is value making certain elements of your UI consistent. Navigation, save/cancel, and error messages for example. A consistent interface makes the user feel like they have a chance of learning it.

Feedback

Key and lock provides instantaneous feedback. Usually the wrong key won't even fit into the lock. If it does fit, the lock won't turn. Although its annoying to run through a ring of keys looking for the right one, consider how quickly you are actually able to do it. That's because of good feedback.

Feedback is vitally important to any interface design. Any and every action must have a clear, unambiguous, unmissable reaction. Change your button's text and disable it once it's clicked, notify that the form saved properly, explain that an error happened and what to do to fix it. Provide good feedback.

Useful Abstractions

Few people truly know how the tumblers in a lock work, and fewer still could design them. Yet the key abstracts the user away from the inner workings of the lock, allowing them to focus on the task (opening or locking the door) rather than how the tool helps them accomplish it.

Software interface design is the act of building abstractions. We abstract the user from the inner workings, on the web for example, of HTTP, HTML, CSS, Javascript, and whatever server-side code involved.

No matter how hard you worked on your code, don't let your ego or frustration leak those complexities into the interface; the user won't understand them anyway.

Want recognition? Do a really, really good job of hiding all that thought and work; make a simple interface to all that complexity, and your users will thank you.

Interfaces that have endured for centuries have done so for a reason, because they rely on UX truths that work no matter what the technology.

Guessability, security, notification, consistency, feedback, and good abstractions are something that every interface (physical, software, or otherwise) should share.

Stay humble in your designs. Seek knowledge from interfaces that have endured the test of time. Build something that people will be happy to use, and you'll be happy building it.

Good Interface, Bad Interface #17

2014-03-01T00:00:00Z

The key and lock is one of the oldest and best examples of a good interface. It’s guessable (there’s only one keyhole in the average door), secure (you have to know and have the right key, but it isn’t hard to use), consistent (know how to use one key, you know how to use almost all), and provides good feedback (key turns or it doesn’t).

Above the all the key/lock interface is good abstraction. Few people truly know how the tumblers in a lock work, and fewer still could design them. Yet the key abstracts the user away from the inner workings of the lock, allowing them to focus on the task (opening or locking the door) rather than how the tool helps them accomplish it.

Interfaces that have been around for centuries have done so for a reason, because they rely on UX truths that work no matter what the technology.

Guessability, security, consistency, feedback, and good abstractions are something that every interface (physical, software, or otherwise) should share.

Good Interface, Bad Interface #16

2014-02-14T00:00:00Z

Drink machine at a local Five Guys. I watched as every single person made some form of mistake during use.

There is a touch screen selection UI, and a ‘Push’ button below it. However the button always says 'Push’, so most push it not realizing they’ve made a mistake in the selection process and something unexpected pours out.

The beauty of old-school drink machines is that they’re hard to get wrong. Each lever corresponds to a specific drink, and the only action available per drink is 'make this drink come out’.

Newer or prettier isn’t always better. Using a new interface technology simply for the sake of the new technology is a fail if you don’t follow the basics of good user experience.

In this case the UX principle broken is feedback. Since one button does many things ('Push’ could mean one of any of the drinks), it fails to follow DOTW, thus good feedback is vital.

For example the button could say 'Push for Coke’ when Coke is selected and 'Push for Sprite’ when Sprite is selected, etc. Feedback of this style allows the user to understand the action they are about to take, and allows them to make a correction before the wrong drink spills into their cup.

Good Interface, Bad Interface #15

2014-02-02T00:00:00Z

A Behringer 802 Mixer. Mixer boards are powerful and useful, but they must be learned. A mixer board is the opposite of a lightswitch, there is nothing obvious or intuitive about it.

There are so many options the user’s best guess is likely wrong (though labeling helps), and the designer must rely on memorization and education on the user’s part to use the device well.

There is nothing wrong with dashboards, portals, hubs, etc - as long as you don’t expect them to be used by new users. Many options means many ways to get it wrong. If you build an interface this way, you must assume memorization and education, not guessability.

So look at your user base and decide: Am I building a mixer board or a light switch?

Good Interface, Bad Interface #14

2014-01-23T00:00:00Z

Walmart. Primary sections, sub sections, and sale areas are clearly marked – yet you still have to stumble around to figure out where you are in relation to everything else.

If you were suddenly transported to a spot like this in the middle of a Walmart, would you know how to get to Electronics?

If you watch people’s user experience at a Walmart, there’s a lot of neck craning, searching for signs of where to go.

Better: Subtle markers pointing to other areas visible from any point in the store.

Navigation in your app or site should meet the ‘dropped in the middle of the site from a search engine’ test.

It may be clear where other related pages are, but can your users tell where they are in relation to your entire site?

Don’t make your users crane their necks to find what they’re looking for. They might just give up and leave.

DOTW: Do One Thing Well

2014-01-11T00:00:00Z

DOTW: Do One Thing Well

The Mantra of the Guessable Interface

In the land of coding there is a principle that defines the essence of modern multi-tier software architectures. DRY: Don't Repeat Yourself.

DRY has become so widely accepted in software design because the benefits are obvious and immediate. Less code to write, less bugs to fix. It makes for less confusing software from the programmer's perspective, which leads to better software for everyone.

The DRY principle is this: "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." DRY works for software architecture. It's about reduction.

In my design experience I have found that there is a very similar UX principle that is equally effective in developing usable (that is, guessable) software.

DOTW: Do One Thing Well

The principle is simple. As with all principles, its application varies depending on the circumstances. If I was to try defining DOTW more strictly, I would say:

Any screen or interface should accomplish at most one task.

Trying to do too much makes an interface less guessable - you introduce too many variables, decreasing the probability of the user's next 'how do I do this' guess being the correct one.

Even power users benefit from this principle. We give power users big 'everything at your fingertips' screens because we expect that they want a screen where they can do it all. However multi-focus screens usually require memorization, and no one's memory is perfect. Single-focus interfaces give less room for error. The less opportunity you give a person to make a mistake, the easier they will feel the software is to use.

A screen that does one thing well also reduces the cognitive load of the user. Cognitive load seems to be cumulative as someone uses software, so the more work they have to do to figure each screen out, the more tired and easily frustrated they become.

Just like DRY, a core idea here then is reduction. Software is about accomplishing tasks. Individual screens should be as focused as possible on a particular task, or aspect of a task, so as to reduce the cognitive load required of that particular screen.

This also has the benefit of making screens more self-evident. You can focus a UI design for a particular screen on accomplishing one task particularly well. It also leaves room to breathe for things like inline help, responsive design, and useful empty and error states.

As I've done work as a database designer, this process reminded me of normalizing a database. Normalizing a database means not storing information in more places than necessary. Normalizing an interface means not asking any single screen to do too much.

I gave my own name to this iterative UI reduction process. I call it interface normalization: Reducing a software interface down to individual screens each representing a single task.

In this process you end up with more individual screens. But I find that the software itself becomes far more usable.

I've been working on generic formulaic examples here. However, there are a variety of examples of the benefits of the DOTW principle and interface normalization in the real world of user experience and product design.

Software Example: Google vs Yahoo!

When discussing the software or website they're paying for, the classic example I give to clients is Google and Yahoo!. Why did Google end up being so much more successful than Yahoo? Obviously the major reason was that Google's search algorithm was so much better.

However, as I think back to the days when Yahoo! was a dominant search engine, and Google began gaining steam, I remember another notable difference that was discussed amongst my internet-loving peers. Google felt easier. It felt easier because it was focused.

When you go to a search engine what is the primary task you want to accomplish? Obviously, search for something. You want to focus your entire cognitive process on accomplishing that task: search. In this regard, Google (still to this day) follows DOTW.

The Google homepage tries to primarily accomplish one thing. Search.The Yahoo! homepage, on the other hand is still stuck in the old 'websites are portals' days. It tries to do a bit of everything on one page.

The Yahoo! homepage tries to be many things, and therefore does nothing particularly well.Imagine that you had never used a search engine before. That you'd never seen neither Google nor Yahoo's homepages. Which would you have found more guessable (i.e. usable)? Which would you have figured out faster? Would you assume Yahoo! is searching the whole internet, or just its content?

Google's homepage is minimalistic. However, this does not mean that Google's website has less functionality. Its homepage simply does a far better job of 'doing one thing well', and as Google added features it didn't dilute its homepage's strong sense of purpose.

The funny thing is, Yahoo! followed the opposite track. Take a close look at the slow progression of its homepage over time, from a more strongly focused, opinionated interface, to the 'throw everything on the screen' approach of today: Yahoo's steady home page transformation.

I give this example to clients who are keen on building portal-like software, and they almost always understand it. Often it has saved me from an unnecessarily difficult design situation, and resulted in something the client was ultimately happier with.

Now think about software or other products that you use, have built, or are currently building. Do the interface screens look more like Google or Yahoo? As features are added, which progression do they follow?

Product Example: Toasters vs Toaster Ovens

The DOTW principle doesn't just apply to software. On my everyday UX Tumblr I use a product example that has always frustrated me. Toaster oven design.

A toaster oven is neither a toaster nor an oven. Nor both. The product designers can't figure out how to deal with that. I have never seen an easy-to-use toaster oven design. Most toaster oven interfaces look like the above. Many dials, many settings, much confusion.

Why are toaster oven controls so often confusing or unclear? Because you are asking the product designer to design for something that does two different things. One dial tries to do multiple things, with no clear feedback. I have burnt more toast than I care to admit.

A toaster follow DOTW. Because it accomplishes only one task, the UI can be optimized for it.Now I've seen plenty of easy-to-use toasters. You set a setting, you pull a lever, you wait. Toast finishing results in audible and physical feedback. A toaster does one thing well.

A toaster oven, on the other hand, is a nightmare of a product design challenge because it doesn't easily allow for a tightly focused interface. One dial often tries to be two things, and feedback can be misleading.

I find it interesting that virtually no manufacturer does a toaster oven interface well. Most just copy each other's flawed designs. It may be laziness. Or it may be that trying to do too many different things in one interface always leads to confusion.

The point is that any interface design benefits from the DOTW principle. The more purposeful your interface, the more self-evident you can make it.

Save Confusion, Not Clicks

From a software perspective, doing one thing well is a design pattern that is contrary to the old assumption that people care the most about reducing the 'number of clicks' you needed to make it through an interface.

In my experience, that is a false metric. What people really care about is, not how many clicks, but the clarity of knowing what to click. Reduce confusion, not clicks. Confusion generates frustration. Make anything less confusing and it will be more popular.

Analyze, Reduce, Retest

The next time you are having difficulty understanding why a design is confusing, ask yourself if it 'does one thing well'. If it follows DOTW. If not, iteratively follow these simple steps:

Split a single screen into multiple by dividing tasks or elements of a task.
Adjust the design of each new screen to optimize for that more tightly focused task.
Retest.
Repeat.

Split your UI across more self-evident screens, and keep testing. You may not need to go that far before you find considerable improvement in user testing. At the very least, you may find inspiration about different ways to flow your UI.

Remember, most of the time, people are just guessing how to use software. Try making each screen do one thing well, and you may do well yourself.

Good Interface, Bad Interface #13

2014-01-09T00:00:00Z

A mechanical pencil follows DOTW (Do One Thing Well). There is only one way to get lead out, and only one option to try. However it breaks down when the lead runs out. How many times have you shaken a pencil to see if lead is still in it?

Better: If, once the lead ran out, a bright red warning piece of plastic came out of the tip clearly indicating the error state.

A simple interface that ‘Does One Thing Well’ is highly desirable and guessable. Yet you must take into account all 3 states of an interface: Empty, Full, and Error.

If you have a clear picture of all three states when you design then so will your users.

Good Interface, Bad Interface #12

2013-12-21T00:00:00Z

Back of a Black & Decker Air Station. Can be powered from a standard plug (AC) or a car lighter (DC), and you choose which. The design doesn’t assume you know which is AC and which is DC.

Actually, it gives various opportunities to figure out which is which, and when all else fails provides the icon of a car to make it absolutely clear. It’s ensuring understanding and educating at the same time.

Labels are good. Labels that assume the user has a specialized vocabulary are not. For example a button that says ‘Check If This Username is Available’ is much better than a button that says 'Validate The Uniqueness of this ID’.

Be sure your labels do not make unreasonable vocabulary assumptions. Better, teach the user new vocabulary through the interface design.

Good Interface, Bad Interface #11

2013-12-04T00:00:00Z

A flashlight is designed to be used in the dark. The simple act of picking it up puts your fingers in the position needed to be able to turn it on. You can turn on a flashlight without having to see.

Actions should be in the most natural positions for their usage. A large form with a save button icon somewhere off in a corner, or an important screen hidden under a four level navigation menu keep the user blind.

The more the user has to hunt, the more likely their frustration, exhaustion, and potential failure.

Good Interface, Bad Interface #10

2013-11-18T00:00:00Z

The doorknob with lock. People on the outside cannot open the door, however turning the doorknob from the inside automatically unlocks it.

Security is important, but that isn’t excuse for software to be laborious. Afford people the ability to both provide their credentials and their intentions.

For example, if they go to a secure area of the software and are forced to log in, after they log in you should automatically take them to wherever they originally wanted to go.

Good Interface, Bad Interface #9

2013-11-11T00:00:00Z

An on/off switch on a desk lamp. A single interface controls both on and off. Since it is the only option, it is obvious by process of elimination. There is also strong and immediate user feedback. “Light off! Light on!” is hard to miss.

Elements of an interface should only perform one function. You can consider a toggle as only “one” function: ‘Off’ is only available when 'On’ and vice versa.

Toggle is less obvious when many interface elements are present, so strong feedback from the action (like 'light on/light off’) becomes even more important.

Good Interface, Bad Interface #8

2013-11-03T00:00:00Z

Portable charger for a car battery. Cords are made to wrap around the charger and lock in place. This looks very nice, but the cords are far too short and makes it extremely cumbersome to connect. This only worsens the frustration you are almost always already experiencing whenever you use this device.

Aesthetics are important, but they are not worth sacrificing ease of use. The best designs are both beautiful and clever. Ease of use is even more important when the functionality is explicitly used under stressful situations.

Good Interface, Bad Interface #7

2013-10-29T00:00:00Z

Panel on a Keurig coffee brewer. Turn it on, main screen says ‘Ready to Brew’, and you choose one of 3 cup sizes. There are no labels, but the clarity of icons and reduction of options makes it self-evident.

Normally labels are needed on icons. However (if the icons are extremely clear, agree with the context, and the interface’s goal is self-evident and highly focused) labels aren’t always necessary.

Good Interface, Bad Interface #6

2013-10-21T00:00:00Z

Back of a vacuum cleaner. How do you turn it on? Once you turn it on, how do you tilt it back?

Primary functions should be obvious. Secondary or related functions should be easily accessed alongside the primary action.

Good Interface, Bad Interface #5

2013-10-16T00:00:00Z

Struck by the brilliance of a tissue box. Not so much that you can get a tissue out, but that the next one is left waiting for you.

Most software is a series of tasks. Make the next logical tasks readily available upon completing the current one.

Good Interface, Bad Interface #4

2013-10-15T00:00:00Z

My toaster oven. Top dial when in the ‘off’ position means oven is off, but toaster is on. The bottom two individually control toast versus oven.

Many a time I have left the toaster thinking it was toasting, when it was in oven position, or vice versa. The toaster ticks, but I return to find no heat, no ready food.

In software each interface should DOTW: “Do One Thing Well”. The more functions any element of an interface carries out, the less likely it is do any of them well.

Good Interface, Bad Interface #3

2013-10-14T00:00:00Z

Dyson bathroom hand dryer.

Good: Where do you put your hands?

Bad: Hand spaces are too small. You inevitably touch the sides which ruins the whole point.

Make it easy. But software has to actually do what it says it will do, otherwise all the other good UX doesn’t matter.

Good Interface, Bad Interface #2

2013-09-24T00:00:00Z

Airplane tray table. How do you open it?

Give your user’s best guess the highest probability of being right.

Good Interface, Bad Interface #1

2013-09-23T00:00:00Z

Single light switch on blank wall.

A self-evident interface doesn’t need documentation. Scannable, limited options teach without words.

Good Interface, Bad Interface

2013-05-12T00:00:00Z

Good Interface, Bad Interface

I have been doing a great deal of traveling as of late. Travel is frustrating. Airports, hotels, car rides and more are filled with other people's design choices. Some are good, some are bad, and they all carry lessons in user experience.

Airport bathrooms, for example, turn out to be pretty diverse in their design choices - and their influence on the traveler's overall user experience is, understandably, intense. When it's bad, it's really bad.

So, when faced with a bad user experience, I apply a simple mantra:

If you see every moment as an opportunity to either teach or learn, life is a lot more enjoyable.

Actually I try to apply this for good user experiences as well. Try to stop and recognize it when you've just effortlessly used some device or process, and ask yourself why it worked so well. Then take that lesson and ask how does it apply to software.

Every user experience you have, whether bad or good, can inform the software you design.

I'll give you an example. I was stuck in an overly small seat in the very back row of an airplane (right by the bathroom). Frustrating. In front of me I saw this:

The view from my tiny seat at 30,000 feet, next to the bathroom.When the crew finally came around with drinks, I pulled my tray table down. I stopped later and asked myself: 'how did I know how to pull the tray table down?' There were no labels. There were no instructions. Yet that was a frustration-free user experience.

Why? Because, I decided, the design of the tray table followed a simple concept:

Give your user's best guess the highest probability of being right.

A lesson I could apply in every software interface I would ever design.

If you look at the tray table, most people would make the same guess as to how to open it. The design makes that best guess the right solution. That is good user experience.

I began to see this everywhere. In the kitchen, on the road, making coffee. So I started a project: Good Interface, Bad Interface

I plan on snapping a shot and seeing what I can learn whenever I am frustrated with an interface, and whenever it was so easy I didn't have to think about it. It's keeping me in a good mental place for design. So far, so inspired.