The Four Stages of Santa Claus for software developers

There is a joke, "The Four Stages of Santa Claus":

  1. You believe in Santa Claus
  2. You do not believe in Santa Claus
  3. You are Santa Claus
  4. You look like Santa Claus

There is an equivalent for software developers when it comes to requirements documents and specs.

  1. In the beginning of your career, you only see complete specs, and you act like Santa Claus brings the requirements in the middle of the night and puts them under the tree.

  2. You realize that someone had to write the requirements, but it's not you. You complain that the specs are not clear or "the customer doesn't know what they are doing."

  3. You realize that you need to write the specs and clarify the requirements, or the project is going to have problems.

  4. You run a software consulting company and it gives you gray hairs :-)

In software development, we have to bridge the gap between the "requirements" side and the "solution" side. That means we have to figure out exactly what the goals of the system are and how we are going to satisfy them, in detail. It's everyone's responsibility to do this, from the product manager and project manager on the requirements side or from the tech lead and dev team on the solution side. There is no Santa Claus, unfortunately.

If you are not doing everything you can, then you are making extra work for other people. Your tech lead or project manager can do it, but they have plenty of other work to do. Sometimes it is a business person, and it causes real problems because you are expecting them to do things that they can't do. Programmers are good at logic, and sales people are good with people. It works a lot better when you understand the business requirements and write up a proposed solution for the business owner to approve.

This is why outsourcing to cheap programmers in the developing world often has problems. The client needs to be able to write the spec in incredible detail. The developers can't bridge the gap because they are too junior or don't have enough understanding of the business context.

Sometimes in projects there is a situation I call "someone needs to think hard and make some decisions." This can happen if we don't get complete requirements up front, or we are iterating on product / market fit. It's also something to watch out for in an agile process where we are implementing cycle by cycle: everyone is doing something that works for this iteration but we still need to pay attention to the big picture. It's easy to coast along without decisions being made, wasting time and causing bad user experiences which need to be reworked.

For example, say we have a SaaS product, so we need a registration and purchase process. The developer says, "tell me what the registration process is." The designer says, "give me the screens and I will make it look awesome." The entrepreneur says "I don't know, I am a business guy".

The best way I have found is to start by understanding / defining your target users with user personas, then determining high level user goals / pain points and their ideal user experience. Then we define user stories which show how the product will help people achieve their goals. Next we go through how the service will work step by step, identifying any problems that may occur and how we will deal with them. I call this the "Director of Operations" view. It's not technical, it's still on the "requirements side", but it's sweating all the details. With this preparation, we can architect a technical solution which meets these requirements. If we skip directly to the technical side, then there is a danger that we will build the wrong thing.