or, The Art of Writing Requirements.

When you are writing software for an end user, if you strip away all the fluff and bells and whistles, you are doing something very simple:

You are solving a problem for someone.

The heart of this issue is a simple concept: when you are writing software, what are the functional or operational requirements?  What is the software actually supposed to do?  For example, if you are building a system for a hotel to manage all its inventory, well then you need to know how that hotel manages its inventory.

Developing requirements is a particular challenge of software engineering that frequently arises.  You could also call this scope.  If you look back at case studies of failed or delayed software projects very frequently the root cause that many of the engineers state was they didn’t have good requirements, or that the requirements changed too much.

As a software developer, especially in a leader role, here’s an important lesson to learn: you’ll probably never get good requirements from your customers or users.  In fact, if you sit there and wait for them to hand you a document full of well-written requirements, you’ll pretty much just be waiting forever.

And by the way, I’ve seen organizations that operate exactly like that.  They never really get going on any projects because they claim that they can’t start until their stakeholder gives them good requirements.  Either they never get any, or the requirements delivered from the stakeholder are subpar and thus rejected, and next thing you know months or even years have gone by and your project has never even delivered a working beta.

Look at some of the successful startups or leaders of industry.  Apple, Amazon, Google.  Where did they get their requirements from?  The answer is, partially at least, that they are really good at getting together and figuring out what users really want.  This is an important skill all by itself, the ability to bring a non-technical person into a room and talk with them and figure out their requirements.

“I don’t like the current software, its terrible.”

“OK, why is it terrible?”

“It doesn’t work right.”

“OK, well let’s look at it.  What are you trying to do?  OK, when you do that, where do you normally click?  Does that do what you want?  No?  OK, then when you click this button what is it you think that the software should do? etc”

Another challenge, especially for the startup, is what I call “looking at the crystal ball”.  This is the art of knowing what customers really want, even if they don’t know how to ask for it or even know that they want it.  Tricky!

Interestingly, sometimes this goes against what your senior management wants to do (“we are not in the business of writing our customer’s requirements!”) but the answer is, yeah you actually are.  Your job is not to receive requirements or specs and then write code; your job is to solve problems.  And in fact, pushing in the “customers write good, detailed requirements” direction is dangerous, especially for the customer.  (I’ve frequently seen this happen, as well.)  What happens is the customer writes super-detailed requirements and specifications, but then halfway through the project when its discovered something needs to be different, now its a big deal to make that change, because of contractual reasons and so forth.

This, by the way, is why I think so many of those really large government software projects fail. The vendors, and the law, demand that the government be super-precise in asking what they want for, but in a very waterfall-y anti-agile way that means that the delivered product, even though it might be exactly as the spec says, is not really what is needed by the end user.  And thus the delivered product, even if it works exactly as asked for, is considered a failure.

I think the industry, in some ways, has realized this and has tools to address it.  Many books and courses in UI/UX design exist, and some people have written some really good books on this topic (Don’t Make Me Think by Steve Krug, or User Interface Design for Programmers by Joel Spolsky).  There is also an entire body of knowledge called systems engineering, not to be confused with systems (and controls) engineering, nor systems (administration) engineering.  Systems engineering is the discipline of requirements elicitation and management, and aligning requirements and efforts across the organization.  Furthermore, this is why the Agile movement is such a success.  Agile recognizes that writing requirements is hard, writing all your requirements up front is even harder, and instead lets you move forward organically with lots of integration and feedback with the end user to help keep you aligned in the right direction.

The takeaway here is deceptively simple, but can be hard to do, both in actually technically executing and in dealing with organizational culture.  But if you are at least aware of this, I promise you it will greatly ensure the chances that what you build and deliver are actually useful and thus successful.