It’s the start of a new project. Everyone is throwing in design ideas. Lot of excitement. Bit of a buzz.
High level architecture is taking shape. Wire diagrams for the GUI are nearly finished. ‘This’ system will talk to ‘that’ system. You know which systems are storing the different pieces of data. Front end will be mobile iOS and Android. We’ll use a REST api to talk to the back end. The design is looking good.
And everybody’s off. All beavering away. All building their own little bit of the system.
Won’t be long before we put all the different parts of the system together for the first time. See it all working as a system.
Sure… we’ll find a few bugs. The Testers will find them. Few fixes and we’ll be up and running.
Then, when everything is plugged together, we start asking, “why did we not stop to look at defining the APIs in detail in that initial design?”
Oh sure, someone mentioned it early on. Everyone was too busy though. And anyway we had a rough idea of which calls and end points we’d need. All looked pretty straightforward.
BUT it’s not. Never has been. Never will be!
The whole damn team, including a tester, should have been locked in a room for 3 days. They should have been confined to that room (with pillows, bread and water if necessary) and not allowed out. Not allowed out until the API calls were defined in detail.
Defining the API is just the BEST opportunity the whole project team have to validate the design right at the start. It’s a huge chance to save a massive load of work and fixes on the back end of the project.
And guess what? It’s fun. It’s interesting. It’s great for team building!
BUT it does take a room full of people, a significant amount of effort and a good bit of brain power to pull this off in the early stages of a project.
The idea is that you walk through every use case, every wire diagram and every requirement. You look at the data that’s needed at every stage. Then pull together a list of all the different calls and the responses.
Absolutely key to this is having a tester in the room. Someone who’s going to ask awkward questions. Maybe even daft questions. Someone who’s going to make life a little bit more difficult for everybody involved. Someone who’s going to push the team to go through the process properly.
It’s a detailed design review centred around the most fundamental component of the project. The API. A detailed design review where the tester pushes “everyone” to test the design on paper before anything is built.
There are so many benefits to running through this early on in the project…
Firstly, everyone comes out of this understanding what’s being built. It’s a process of educating everyone in the team.
Secondly, you will find bugs. Significant bugs in the design up front, early on in the project life cycle.
Thirdly, if you’ve designed the calls and data up front you can mock the services. Then each part of the team has something concrete to work with.
I don’t care if you work in an agile fashion and you’re going to build little bits at a time. You know the “we’re using agile – everything will be okay” kind of mentality. That’s like going on a 1000 mile road trip and only buying a map at the start of each 100 mile section. You wouldn’t start out on that trip without looking at a high level map to validate you’re heading in the right general direction.
All sounds so simple. So logical. Such a smart thing to do. But do we do it? No.
I’ll tell you this though, you’ve only got to see this work in practice once and you’ll do it on every project you work on. Every time.
Try it!
