Morris Brodersen

Outlining

Sun, 01 Feb 2026 00:00:00 GMT

I find it difficult to “teach” staff-level software engineering work (system design, technical planning, etc.) as there are no hard and fast rules. On the contrary, it’s about knowing when to break the rules, which requires experience and getting comfortable with ambiguity.

These kind of skills are best acquired by working on real projects, with real constraints, and expert guidance. However, those projects are (rightfully) limited; it’s hard to get enough exposure for people in an organization to level up consistently.

To fill this gap, I’ve recently started a workshop format for practicing system design and technical planning called outlining. It features a powerful overlap of deliberate practice and real work, and goes like this:

Pick (or invent!) a realistic, unplanned project in our context.
Find a small group of interested people (3-10 people).
Pick a time box (1-2 hours).
Meet and work on a rough outline for the given project (tasks, questions, risks, and so on). Bullet points and diagrams only!
Log the result; actual implementation or following up is not required.

It sounds simplistic, but so far these workshops have always been fun, intense, and uniquely rewarding. We discuss project requirements, architectural constraints, and dive into existing systems and code to understand how the given project could fit in:

What data needs to be gathered and processed?
What system components need to be changed, in what order?
What trade-offs do we need to make based on known constraints?
What difficulties, risks, and second-order effects can we anticipate?
How might we find answers to open questions?

Working these kind of questions in the context of a real system we’re familiar with, but without the pressure to implement or report, provides a frame just right for learning and knowledge building. Groups are often a mix of experts and active listeners of any level; that way, anyone can get exposure, but the group can always make good progress.

Besides leveling up the team, I’m seeing some additional positive effects:

Increased estimation quality
Increased domain knowledge
Deeper understanding of our own systems
Reduced barrier to tackle difficult technical migrations

Best of all, features which were considered “impossible” before became tangible through outlining, and some have made it into production!

Here are some more practical tips and tricks for outlining sessions:

Use the outline as a “working memory” for the group. Start with a blank page, then write down notes, thoughts and open questions as you go, even if you resolve them later. That way, you can park items mentally and revisit them later.
Work the subject breadth-first, i.e. start on a high level and only go deeper as time allows.
Do not remove incomplete items when closing the session, as they can provide valuable insights.

Happy outlining! ∎

The Power is in the Network

Thu, 28 Aug 2025 00:00:00 GMT

... or, why LLMs have no place in internal communications of high-performing organizations.

Organizations depend on their inner relationships. The quality of these relationships often make or break an organization’s mission: Is there enough trust between peers to collaborate? Are leaders able to motivate and inspire? Are we willing to make sacrifices for each other?

Relationships are shaped by communication, with all its facets. People read far between the lines, looking for authenticity and care, not just raw information, in every signal. Relationships suffer when we’re unable to connect to the person behind the signal.

Communicating with the intent to connect requires authenticity. Being authentic can be difficult and uncomfortable, especially in writing¹. Writing well takes time and practice, and unfortunately, there are no shortcuts. But whatever you do, do not reach for LLMs.

LLMs are hopeless at producing communication fit for building relationships. There is no chance an LLM can get enough context about a specific situation and the involved people to consistently produce authentic text.² We would have to provide books worth of context, not to mention that not everything can be described with words.

LLMs don’t know about shared history or values, prior conversations, the individual needs of involved people, the little social cues of the day. When we speak to someone, we tap into those things intuitively. When using LLMs, it’s unreasonable to provide so much context upfront, and it’s not enough to add a personal touch onto an LLM-generated draft³.

LLM-generated text erodes relationships. Weaker relationships lead to weaker organizations. It’s really that simple.

Don’t send LLM-generated walls of text to your colleagues. They don’t care that much about grammar. They don’t care about crucial. They care that you care, and they are trying to see you behind the message.

Don’t summarize texts your colleagues have put time and energy into. You’re missing out on a chance to connect to them, if only by understanding them better. If a text is too long, let the author know why you think that. Show them that you care about what they wrote.

LLMs will always, by design, be perfect strangers, through which we cannot hope to communicate with honesty and care. LLMs may or may not be fit for other things, but using them to communicate within organizations is indefensible.

The power of a high-performing organization is in its network of relationships. People that feel connected and cared about will care about the organization in return. Taking the time to really communicate with your colleagues is the most important sign of care, and must not be replaced. ∎

When in doubt, write how you would speak. ↩
Technically, it could be possible: We just need to introduce total surveillance, and grant LLMs full access to the tapes. Let’s not. ↩
That’s the modern “shit sandwich”: Beginning and ending have a personal touch, but the middle is generic LLM slop. ↩

Designing Together

Thu, 24 Jul 2025 00:00:00 GMT

Some time ago, I helped build a small translation feature. Our users regularly needed to translate some of their assets, and we figured it would be straightforward to integrate translation right into our platform. In the morning, I received a UI design file and got to work.

In our backend, translation was already available as a reusable primitive. Based on that, implementing a user-facing endpoint for translating this specific kind of asset took less than an hour.

As for the frontend, there already was a context menu for each asset. The UI design featured a new “Translate to...” menu item, which was supposed to bring up a submenu of available languages.

Unfortunately, our component library didn’t support submenus yet. For a moment, I was stuck; in my experience, getting submenus working just right is non-trivial, and I felt chasing robust submenus right now would only yield marginal value (if any).

However, our component library did have dialogs, so I went and made the new menu item open a separate dialog for language selection instead, which worked well. I shared a screenshot, explained how submenus are probably not worth it, everyone agreed, happy merging.

The feature landed in our staging environment in about two hours, which was a nice turnaround due to fast pipelines and robust tooling. We were able to play with it, adjusted some details, and were ready for production before lunch.

This small anecdote may sound like “just another day at the office”, but in my experience, there are plenty of potential failure modes here:

Not even looking for more economical alternatives, missing an opportunity
Taking on the submenus without informing anyone, risking a delay
Rushing the submenus, risking bugs
Handing the issue back to the UI designer to come up with alternatives
Insisting on the marginally better design, even if high effort
Not seeing that submenus can follow in a later iteration
Delegating the UI work to the maintainers of the component library
Complaining about it as a planning mistake

I’ve been guilty of all of these in similar situations. I know any of those decisions could have meant days of additional lead time for this one simple task, without adding significant value. If you do dozens of such tasks, costs compound quickly.

While there is no silver bullet for avoiding such inefficiencies altogether, I believe the one thing we got right this time was sharing the design process, beyond the handover of the UI design file, and beyond our individual roles. In the words of one of the most important American designers of the 20th century:

Here is one of the few effective keys to the design problem: the ability of the designer to recognize as many of the constraints as possible, [their] willingness and enthusiasm for working within these constraints. The constraints of price, size, strength, balance, time and so forth. Each problem has its own peculiar list. — Charles Eames

Rather than thinking in terms of planning and resources after the design phase, we saw timing and effort as design constraints to work with, and made significant adjustments to our initial design based on these, even late in the process.

In software development, you want this to happen, and often. This is how you win back efficiency lost to unknown unknowns, and save opportunity costs better spent on chasing the next big thing.

To me, this is the ideal of cross-functional work: Embracing constraints from outside our bubble, taking an economic perspective, and designing together. ∎

Functional Core Diagrams

Mon, 10 Feb 2025 00:00:00 GMT

I often follow the functional core, imperative shell way of constructing software:

Isolate business logic into a set of pure functions (the functional core).
Implement side-effects and mutable state in a thin layer around the core (the imperative shell).

This not only shapes how I write code, but also how I think. When designing a software system, I’ll assume the functional core and the imperative shell are independent. This allows me to ignore servers, storage, networks, and other technical constraints when starting out.

Instead, I can focus on data and functions in the abstract, which are (by definition) enough to describe the functional core of the system: What needs to be computed, and from what? What intermediary data and functions can I anticipate?

I’ve found drawing the flow of data types through the functional core to yield useful system diagrams. For example:

This article illustrates the properties and use of these functional core diagrams.

(I’m probably reinventing some wheel here. So far, I haven’t found a diagram type with the nuance I’m looking for. A data-flow diagram comes close, but it’s a bit too rigid. If you can think of something, let me know!)

Definition

A functional core diagram (FCD) is a directed graph with two kinds of nodes:

Types
Functions

An FCD allows the following edges:

Arguments: Types point to functions accepting them.
Results: Functions point to their return types.
Subtypes: Types point to their subtypes (if any).

Types and functions are abstract. They need not reflect a concrete implementation, but should have clear semantics.

I use rectangles for types, and hexagons for functions, but any distinct shapes work. Types are in noun-form, functions are in verb-form. Colorings may group types and/or functions.

Usage

I use FCDs to explore potential layouts for a software system. I start with known inputs and outputs and connect the gaps with (abstract) functions and intermediary types, until I’m confident the design is sound.

While drawing candidate diagrams, I’ll look out for various system properties:

Dependencies
Coupling
Module boundaries
Transaction boundaries
Standard data types
Opportunities for caching
Opportunities for concurrency
Hot paths
etc.

When I identify a problem (e.g. unnecessary coupling) I’ll try to refactor the FCD, almost like code. In that sense, FCDs are like graphical pseudo-code.

For example, the introductory diagram can be refactored to be less coupled to the CSV format, and support additional output formats:

Notice how the new type for chart series emerges as a natural boundary, something immediately visible in the FCD. (Adding support for more input types is left as an exercise for the reader.)

It’s hard to pin down the list of things to look out for, or when and why to refactor. Like with many skills, it takes a bit of practice to build an intuition and get good results.

Colorings

I use colorings to group types and functions by various properties. For example:

Which module is responsible for which function?
Which data needs to be persistent?
Which workloads belong on the server-side, which can be run client-side?

The following is a real-world FCD with a coloring specifying where to implement functions in a service-oriented architecture (labels removed):

Discovering the dependency on the yellow function in the upper right early saved us from a difficult refactoring later on.

Abstraction

FCDs allow abstraction and imprecision by design. For example, listing all inputs and outputs of a system and connecting them by one big function is a valid FCD, however useful. On the other hand, an FCD laying out every type and every function of a concrete implementation is probably too granular.

Being able to explore this “search space” graphically feels both natural and powerful. Finding the right level of abstraction is key—just enough depth that I can confidently explain the system to myself and others, but not more.

Limitations

Not all system designs benefit from an FCD. For example, systems where efficient I/O is an inherent goal (e.g. databases, video streaming, etc.) often have a shallow functional core, and the design problems are found in concrete technology or infrastructure.

FCDs don’t capture choice, temporal order, or relations between types. For these purposes, consider activity diagrams, sequence diagrams or entity relationship diagrams.

Finally, functional cores are generally not independent from imperative shells. At some point, we have to invite the real world in (computers, memory limits, networks, etc.) and may have to adjust our functional core to fit these constraints.

(Incidentally, the moment when I have to adapt an otherwise ideal functional core to fit the real world has become my definition of accidental complexity.)

Conclusion

FCDs are no silver bullet, but I often find drawing the functional core of a system a worthwhile exercise. Most of all, I enjoy the organic construction of FCDs: I can start with a diagram as simple as one big function, and refactor it until I’m satisfied with the level of detail.

I suspect there are some fundamental properties making FCDs effective (category theory comes to mind). In any case, I hope I was able to present FCDs as a practical, useful tool for system design. ∎

How Do You Like What You’ve Built?

Fri, 03 Jan 2025 00:00:00 GMT

Recently, a colleague asked me for a code review on some complex UI changes. The idea was to make an error-prone form easier to use by displaying warnings in the right moment, and automating various state changes in the background (think “smart configurator”). The requirements were given upfront, so my colleague was in execution mode, turning these requirements into code.

Glancing over the pull request, nothing stood out as problematic, but I didn’t feel ready to approve the changes before playing with the new UI.

However, before testing it myself, I asked (via chat message):

How do you like the new behavior?

I went to grab a coffee; when I came back, they had answered with roughly the following:

Not sure, to be honest.

A couple minutes pass...

It feels a bit off, like sometimes I can’t really make the changes I want as a user.

Another pause...

Actually there’s still another bug I need to fix, let me get back to you. This needs to be rock-solid for our users!

I can only assume what happened in the meantime, but it seems asking them for their opinion (and not responding for a while) was a cue for sanding the UI, with great results: In the end, a problematic requirement was dropped and multiple commits were added before the actual review.

Later, knowing how the author had engaged with their solution, reviewing and approving the changes felt very comfortable.

I find it remarkable how a simple question can have such an outsized impact. Of course, my colleague’s particular reaction to it was fantastic, and not to be taken for granted. They took ownership and got to work, and were able to critically look at the requirements and their solution. Thank you!

In any case, I believe asking engineers how they like what they’ve built to be a useful trick to try from time to time. I suspect only upside. ∎

On Agility and Friction

Fri, 27 Dec 2024 00:00:00 GMT

I find it useful to treat agile software development as an outcome, rather than something we can adopt. Taking that perspective, we can invert the problem and ask:

What is making us less agile, right now?

The answer is often surprisingly tangible, and rarely about missing agile methods. It is about the concrete friction we encounter when trying to get work done. For example:

Slow builds
Deployment dependencies
Cumbersome software architecture
Recurring manual verification of changes
Hand-overs
Silos
Gatekeeping
Firefighting

In high friction environments, making decisions is risky. Change is slow, therefore making bad decisions is expensive, and therefore more time is invested in planning in order to avoid bad decisions. In the worst case, new controls are introduced, resulting in more friction. These environments become less agile over time, regardless of any agile method.

To break this cycle, fixing obvious sources of friction is often easier than reaching for new process:

Reduce pipeline times
Enable continuous integration
Enable ad-hoc production deployments
Enable self-service infrastructure
Simplify development environments
Fix regular sources of bugs
Add automated checks
Increase observability
Disband committees
Training

This list is widely applicable; none of these actions require organizational change, but will make most organizations more agile (as in, able to react and adapt to new information more effectively).

Interestingly, most agile methods are all about avoiding friction, if you read them carefully. One could even argue that friction is just the other side of the same coin.

However, reducing friction, as an explicit approach or as a goal, is inherently simplifying and empowering. It is a natural driver towards less overhead. It is descriptive and actionable, not prescriptive. It is easier to rally behind removing friction than to convince an organization to adopt new process, roles, or ceremony, which is almost always disruptive.

Note that friction is not a set of things to optimize individually. Some friction can be good in the long term, and there may be complex interactions between different kinds of friction. Mandatory code reviews, for example, can be considered an expensive slowdown, but can act as training.

Managing friction is a design problem, and should be a first-class citizen of any software development strategy. True agility emerges when friction is low, while process, roles, and ceremony should be of secondary concern. ∎