Avoid long pages, numerous meetings and planning to the n’th degree. Plan just enough to get started. Here is why…

The summer of 2002

It was the summer of 2002, we were a team of 12 architects, engineers & analysts who had just finished the gruelling 6 month slog of defining and finalising the DDS (Detailed Design Specification). It was a thing of beauty; a behemoth 250 page document of hand-crafted flow charts, sequence diagrams, references to external ICD’s (Interface Control Documents) and the culmination of months of meetings, workshops and design sessions. As we sat there sniffing the sweet scent of those old HP Laserjet printers churning out our glorious creation, we sipped coffee from our large black cups provided by the de facto management consultancy of the time. We high fived and felt as though we had summited mount Olympus; what a glorious time to be alive. There was only one problem and it was haunting us; it was a work of fiction.

THAT project meeting

Fast forward about 9 months, with 3 months left to day zero. We’re all sitting in the large meeting room, some stale doughnuts in the corner and that awkward chatter groups have at the start of a project meeting where a bomb is about to burst.

Bob (not their real name) was the first to go. Now let me say this, the man’s a genius with project management certifications I can’t start to list and the wondrous ability to quote page and verse from SOX 101 on request.

Unfortunately Bob’s a theory man; he’s never launched a full production system in his life… As I was saying, he started the proceedings and wasn’t holding back. “WTF do you mean the end user subscription service can’t communicate with the outbound messaging interface?! That’s a crucial part of the end-user experience, we spent months documenting those API interactions and work-flows.”

Charles from the messaging interface interjected, “Dude!!! Do you remember those security certification requirements that were enforced 3 months ago? We were forced to apply a brand new auth system to maintain compliance, were you not included in the memo’s?”

This was the general tone of THAT project meeting and more was to come. Our glorious creation finished 9 months ago was quickly proving to be a very expensive exercise in tree killing and paper stack generation… Where had we gone wrong? How did we not see this coming?

Adapt or die

Numerous post mortems were held, meetings filled with jars of coffee and expletives, deep dives and open, honest discussions. The result of all the additional time and effort left a clear picture. Our organisation, like any other, was a giant organism and if you don’t adapt to change, you die. This led to the now obvious problem, one we’ve probably all experienced: documentation is old by the time it’s printed.

Are you saying don’t plan?

Now if you’re thinking I’m suggesting you don’t plan, take a deep breath and continue reading.

Always have a plan, let me repeat that, ALWAYS HAVE A PLAN.

Without a plan you don’t know where you’re going. Here’s the thing though, if you’re driving from London to Cairo, you know you need to head east and probably need to make a right turn to head south at some point. Do you know which road you’ll drive from Tanta to Cairo? No! And let’s be honest, until just now you didn’t even know about a town called Tanta, you didn’t know the name of the main road through Tanta either! FYI it’s Alexandria Agriculture Rd.

The point is; there are things you don’t know now. This is typical for almost every software project. The mythical “known-unknowns.” If you knew you didn’t know them, they’re not unknown right?!

Just In Time Specification

This brings us to the methodology we started embracing in our organization during the summer of 2003. At that point it was the only option we had. Now it’s the only option we choose. Have a plan. ALWAYS have a plan. But keep the detail at a high level. Ensure your teams design for integration using self-documenting API’s from day one. Accept that integration between the end user subscription system and the outbound messaging interface will take a few days, not a few hours.

Once you’ve got this JITSpec thing down - which seems a little scary at first - you’ll notice how much more mobile your team becomes. Integration with the payment system? No stress; call the payment team and setup an integration session to get the up-to-date spec and API requirements. Have the UX team mock out their flow leaving stubs for the payment system. The UX team can build and test the user flow while the backend team builds the integration framework with the payment system. Once the integration is completed and tested, simply replace mocked out stubs in the UX with the live production code. Oh, and you may have noticed that your mock stub is enabling your system for CI/CD!

You can thank me later.