The Code's the Thing

Sat thinking about management, technology and organisations, which is rarely a good sign.

Specifically, I was thinking about the old argument between waterfall and agile, and all the management furniture that sits around it: ITIL, PRINCE2, ISO 27001, risk logs, control spreadsheets, governance packs, delivery boards, project plans, dependency maps, steering committee decks.

A lot of these things exist to create certainty about the world. Or at least to make uncertainty small enough that someone can pick it up, own it, and carry it out of the room as an action.

Waterfall does this by trying to describe the thing before the thing exists. Agile, when it works, does something different. It tries to make the thing exist as early as possible - as working software.

Documentation as control

There is a tendency in management to treat documentation as a way of controlling the future.

Write the requirements down. Produce the plan. Fill in the RAID log. Agree the milestones. Map the stakeholders. Define the operating model. Review the service transition checklist. Put it all somewhere SharePoint can slowly digest it.

None of this is inherently bad. Documentation is often necessary, especially once a team boundary is crossed. A small project team can get away with shared context because people are talking every day. They update each other constantly. They notice when someone has misunderstood something. They can point at a thing and say, "No, not that bit, this bit."

But outside that small circle, mental models do not travel very well. A user story might be a placeholder for a conversation, but that only works if the conversation can still happen. The minute you need to hand something to another team, an auditor, a support function, a supplier, or yourself six months later, the placeholder starts to look a bit thin.

So we write things down.

The problem starts when the document becomes the main artifact rather than a supporting one. At that point, we are no longer documenting the work. We are hoping the document can substitute for the work.

What agile actually learned

The thing that gets missed about agile is that the useful bit was not "have more conversations" or "put things on sticky notes".

Agile that really worked came out of extreme programming. And the point of extreme programming was that you had working software from the beginning. Not eventually. Not after the analysis phase. Not once the governance board had blessed the delivery roadmap with a ceremonial biscuit.

From the beginning.

The working software was the thing that reduced uncertainty. You could run it. You could inspect it. You could change it. You could find out what broke. You could show it to someone and get a reaction that was based on something real rather than everyone's private interpretation of a diagram.

That is why agile becomes untethered when it does not deliver software. You can have stand-ups, retrospectives, planning sessions, sprint reviews, showcases, backlog refinement, delivery leads, product owners, scrum masters, Jira hygiene, and enough velocity charts to tile a downstairs bathroom.

But if there is no working thing, the whole scenario drifts off into unreality and ceases to bite.

You have retained the meetings and lost the mechanism.

Software exists to do a task

It is worth being plain about why working software matters so much. Software is built in order to perform a task. That is what it is there for. A piece of working software in production is a working piece of technology doing work.

And once it is in production, it compounds.

You do not start from scratch next sprint. You start from something that already runs, already serves users, already handles edge cases that took weeks to find. The next increment builds on the last one. You go from something that works to something that works better, or scales to more users, or covers more use cases, or runs more cheaply, or fails less often.

This is the bit that makes agile worth the effort. Not the rituals. The compounding. Each cycle, the artifact you leave behind is a little more capable than the one before, and the next cycle starts from there rather than from a blank page.

Waterfall, in its purest form, struggles with this because it treats the project as a single arc with a single delivery. Compounding is something that happens to other people's products, after yours has been signed off and handed to operations.

The artifact has to carry the weight

This is where middle-management agile often gets into trouble.

I have seen attempts to apply agile to layers of management where the main artifact becomes a whiteboard. Usually a Mural board or something similar. Everyone adds their thoughts. The thoughts are grouped. The groups are named. People vote with little dots. Someone uses the ❤️ at least once.

Then what?

Sometimes it works, if the cards become actions. A thing to do. An owner. A date. A decision. A change to a process. A document updated. A service improved. A team unblocked.

But often the board is just a record of a moment when people talked. It captures the room, but it does not do much after the room has gone. It needs people to keep animating it. Without that, it becomes a polite graveyard for ideas that were briefly exciting at 11:20 on a Tuesday.

Software is different because software can grow.

A spreadsheet can grow too. A spreadsheet can run a business, sometimes alarmingly. A risk log can shape the behaviour of an enterprise because it persists, has structure, accepts updates, creates obligations, and can be reviewed. It is not always beautiful, but it has a kind of institutional gravity.

A whiteboard struggles with that. It is the record of a meeting, not a mechanism, or a system whose value can compound.

A note from the bench

I should be honest about where my own bias comes from.

I have always preferred working in agile environments, and the reason is fairly simple: my background is as a programmer, and that means I am someone who can deliver working software in production. I am not usually the originator of the design, or the person who had the insight that the software was worth building in the first place. That is almost never me. But as part of a team, I have the right kind of skills to turn an idea into something that runs.

So agile suits me. The cycle of build, ship, learn, build again is one I can actually contribute to at every turn.

That is also why I have always been defensive of agile when people grumble about it. But I have to admit that in the few cases where I have worked in an agile way on teams that did not deliver software, or did not deliver the outcomes the work was supposed to produce, I have found it frustrating. The ceremonies without the artifact really do feel hollow, and the people complaining about agile in those contexts are not wrong. They are noticing exactly the thing this piece is about.

Code, models, and the AI bit

The code's the thing, really.

That was the lesson agile taught, or should have taught. Not that documentation is bad. Not that plans are bad. Not that conversations are magic. The lesson was that the most useful artifact is the one that can survive contact with reality.

In the AI era, this does not really change. The thing we leave behind is still software. A system built around a language model is still software. The model is a component inside it, but the working thing in production, the thing doing the task, the thing users hit, the thing that gets monitored and improved and extended, is software.

So the rule still holds. You leave behind working software in production. You compound on it. You build the next thing on top of the last thing rather than starting again. The fact that part of the stack is now a model rather than a hand-written function does not change the discipline.

If an AI-assisted team does a lot of clever thinking and leaves behind no working system, no improvement to an existing service, no new capability in production, then it has not really controlled much uncertainty. It has just converted uncertainty into confident language.

We already had plenty of tools for doing that.

The wrong lesson from agile

The wrong lesson from agile was that talking is better than writing things down.

The better lesson was that working things are better than imagined things, and that working things compound while imagined things do not.

Conversation matters because it helps shape the next increment of the working thing. Documentation matters because it helps the working thing travel beyond the original team. Governance matters because organisations need memory, accountability, and control.

But none of them should become a substitute for a system that works.

What did you leave behind that works, and what are you going to build on it next?