The Art of the Spec

How to Write Relevant Software Specifications for the Agile Age


Most fledgling software entrepreneurs aren’t technical. They’re service providers, marketers or salespeople who have identified a personal need or an opening in the market that they want to exploit. An outsourcing firm or freelancer is retained, the vision communicated to the best of the customer’s ability and the team sets off to build the product with all the cheery optimism of a team of artisans building a cathedral.

Months later, after scope creep and communication breakdown have had their way with the project the once-optimistic entrepreneur is a broke, nervous wreck. The development team is buried in technical debt incurred by dozens of change requests and incomplete feature descriptions. The product is incomplete, barely-functional and bears more resemblance to a pile of rubble than the grand cathedral imagined in the beginning. All parties involved are pointing fingers and assigning blame.

Nobody wins.


In this age of agile development, the “move fast and break things” mantra and bootstrapping entrepreneurs, “spec” is a dirty word. It evokes memories of reams of paper which languish, ignored, as an under-resourced development team pumps out work in spite of the requirements passed down by out-of-touch management.

The reality though, is that a specification document is vital if you want to execute a successful software project. The old spec is dead, there’s a new spec in town and following this process can make the difference between success and failure, particularly for non-technical founders.

This series, published weekly on Sundays, will take you through the process of crafting a software spec for the modern age, from nascent idea to mature product roadmap.

We’re going to be developing a spec for our fictional product, a web marketplace that connects businesses in complimentary industries and facilitates partnerships between them. Like any idea in the early stages, it’s still very rough and we don’t even have an elevator pitch or catchy domain name yet.

We’ll start with how to break down your project and think about it from a user-focused perspective, how to translate your vision into a definition a development team can execute against and we’ll wrap up with the realities of scope and how so many people get it so wrong. Along the way we will supply the resources you need to build your own effective specification document and guide you through the process.

Follow our brand new Medium publication The Artisan Journal to receive each instalment in your feed each week.


The Art of the Spec: Contents

Preface (Current Article)
Part 1: Define Your Market
Part 2: Archetypes, Personas & User Stories (Coming 17th April 2016)

Like what you read? Give Dan Cowell a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.