Reject Agility, Embrace Specification22 Jun 2026<br>Reject Agility, Embrace Specification
Here's a reproduction of the infamous "Waterfall Diagram", from the landmark<br>paper<br>Managing the Development of Large Software Systems (Royce, 1970):
SYSTEM<br>REQUIREMENTS
SOFTWARE<br>REQUIREMENTS
ANALYSIS
PROGRAM<br>DESIGN
CODING
TESTING
OPERATIONS
Behold, the enemy of Agile! Although, in its defence...
This diagram was the second of 9 figures, each showing a more sophisticated<br>and realistic approach to software development than the last.
It's almost 60 years old ("Program Design" and "Coding"<br>is a distinction that makes a lot more sense in the era of batch<br>compilation)
It's much better than my realistic diagram of the Agile Model:
CODING
NONSENSICAL<br>AGILE<br>CEREMONY
(Keen-eyed readers will note that unlike the Agile Model, the Waterfall Model<br>actually terminates...)
But I bring up the "Waterfall Diagram" because I am writing about<br>specifications, and in doing so I inevitably open myself to<br>accusations of Waterfallism. For just as the fall of Rome marked the beginning<br>of the Dark Ages of Western Europe, so too has the publication of the Agile<br>Manifesto marked the Dark Ages of Software Engineering; our present age of<br>superstitious planning rituals, and broad literary collapse. And to argue in<br>this Dark Age that extensive writing - or indeed thinking - should<br>precede or accompany the development of computer programs is to invite<br>hostility.
And so I will face this foursquare; and
much as the Anglo-Saxons once looked upon the ruins of Roman Civilisation, I have looked upon the Ruins of Software Engineering (beautifully preserved<br>in the aforelinked PDF scan), and I have striven to find a new way forward. In<br>later years the Renaissance was sparked by the re-discovery of the classics;<br>and it will be the same, I think, for us.
Specifications in a Modern Style
Why won't people write specs? People claim that it's because they're saving<br>time by skipping the spec-writing phase. They act as if spec-writing was a<br>luxury reserved for NASA space shuttle engineers, or people who work for<br>giant, established insurance companies. Balderdash. First of all, failing to<br>write a spec is the single biggest unnecessary risk you take in a software<br>project. It's as stupid as setting off to cross the Mojave desert with just<br>the clothes on your back, hoping to “wing it.” Programmers and software<br>engineers who dive into code without writing a spec tend to think they're<br>cool gunslingers, shooting from the hip. They're not. They are terribly<br>unproductive. They write bad code and produce shoddy software, and they<br>threaten their projects by taking giant risks which are completely uncalled<br>for.
— Joel Spolsky,
Painless Functional Specifications
So what do I mean by specifications, or specs? Broadly; non-code artefacts<br>that describe software problems and solutions. It can describe a vision of<br>software before it exists, or be an audit of a current system. But its purpose<br>is to describe how software should behave, how it should be built, and where<br>it should sit in the world.
(Some might prefer to call these "requirements", or "design docs". IEEE<br>defines an alternate model on
page 46 of this document
which may suit you just as well (or better). If your terminology or taxonomies<br>differ - use them! My goal is not to convince you to follow my model<br>precisely; the goal is to convince you that yours is worth specifying.)
Kinds of Specs
-->
Operational<br>Functional<br>Technical<br>COMPUTER CODE
Software exists in multiple contexts, from corporate strategy to code, and<br>rarely will one document satisfy everyone. A technical specialist likely cares<br>little about the business goals software is meant to meet, and likewise board<br>members might be bored to tears hearing about algorithms and architecture. And<br>again, the way I've split contexts here is not prescriptive; words like<br>"product" or "systems" may appear in your own definitions, or you may have<br>four instead of three; season to taste. The important things are:
Different contexts are of interest to different stakeholders.
An outer context provides a foundation for the inner context.
Recognising that a change in an outer context will trigger a change in inner<br>contexts.
(There is arguably an even larger context missing here; the Strategic Business<br>context. To this I will do something a consultant should never do, and admit<br>I do not have enough experience here to intelligently talk about it.)
And finally it's worth noting that the borders between different contexts will<br>always be blurry, and a good spec author welcomes feedback and input. If<br>something in say the functional specs turns out to be infeasible technically,<br>this is useful information! Communicate, and do not build on things blindly.
Operational Specs
All software exists in some operational reality, larger than itself.
User roles: internal and external (i.e. Suppliers, Customers)
Workflows (i.e. Order Processing, Manufacturing)
Constraints...