Requirements that work

Two posts on Requirements. Two! This guy must be a major process weenie!

No, ask my friends, I am not a process weenie. Getting the requirements is the first step towards a successful project. Do this right and the rest flows like fine wine. Do it wrong and the project is a Death March to hell.

The requirements document is the root document for the whole project. From this one document, the engineers figure out what to build, and how long it will take, the marketing people figure out how much to charge, and the users figure out if they want to give you money. It simply has to be right.

Everyone who read the email had a vision in their head about the CarNet Player. You probably pictured it in the dash of your own automobile. I am also 100% confident none of us had exactly the same picture. The requirements will remove the variation in each persons mental picture until will all see the same thing. They help us remove ambiguity.

Here are my suggestions. Nothing will make this easy. Did I mention Requirements are hard?

  1. Read the books! Read them now, not while you are under pressure to produce the document.
  2. Take all the time you need. We can not do a schedule without the requirements? SO make a schedule to research, interview, and write the requirements.
  3. Requirements are Unlimited. Yes, unlimited. Reach for the moon, ask for everything and leave no crazy idea out. If you can not implement cold fusion, it is OK. We will trim the possibilities later.
  4. Get the right People. First, don’t get the entire engineering, marketing and sales team together in a big room and announce the next great thing. Get a few people who represent each group and start the process. When you have the requirements specified, you can actually answer some questions about the next great thing. The big announcement will go much better.
  5. Keep the requirements and business case separated. Most people think it is good to keep the requirements separate from the functional specification. We don’t want technical details in with the requirements. Along the same lines, keep the business case out of the requirements.
  6. Don’t confuse features with functions. Requirements specify functions. Playing audio is a function of the CarNet Player. Playing an MP3 format file is a feature. Specifying features limits the implementation.
  7. Don’t make a Swiss Army product. Products that do one thing and do it well work much better than all things for all people products.
  8. Ask inside the company first. If, like me, you are starting from scratch, there is no one to ask. If you are in an established company, interview the people you work with. Customer service is the best place to start. They will definitely have a list, and be glad to share. Sales, manufacturing, engineering, even the billing people in accounting should be considered. These people will want to talk to you, not just say ‘whatever’.
  9. Use a tool. If you have access to one, use it. Learn the language of the tool and use it well.
  10. Test the requirements. Do a review, walk through and formal review.
  11.  Put the requirements under change control. Once you have version 1.0, don’t make changes without reviewing them. At the root document a requirement change will change many other realted documents. Use a traceability matrix to keep track of related documents.

Use Functions, Attributes, Constraints, and Preferences

This is taken from Exploring Requirements: Quality Before Design by Donald C. Gause, and Gerald M. Weinberg. Their way of classifying requirements is very helpful.

A function is the what of a product. It describes what the product will accomplish. These are the actions the product performs. For example, the CarNet Player must be able to play audio. Playing MP3 format files is a feature. Separate functions would be how it gets the audio, stores the audio, and so on.

Functions are classified as evident, hidden or frill. An evident function would be that the player must fit into a car.

Attributes are desired characteristics. These describe the product. Things like user-friendly, reliable, manufacturable, safe, and low power are attributes.

Classify attributes into Must, Want, and Ignore.

Constraints limit attributes. These are the testable items in the requirements. An attribute the product must have is limited by the constraints.

If we say the player can fit into a car, that gives a lot of leaway. Something that plays music and fits into a car would be Doug and his guitar. If it must fit into a standard size car stereo enclosure, we have constrained the size. We can put a number to it of X by Y by Z. This can be tested.

Preferences are desirable but optional constraints. Some solutions are preferable. If we can deliver all the must have attributes within the constraints we are done. That may not the the preferred solution. Preferences give us guidance. We prefer the player supports all audio formats. If it can not, we still have a product.

Make the constraints, and preferences measurable. We don’t have to know exactly what fast is, but if we can measure it we can find out.

We are done, now what?

First, test for ambiguity. Poll people about the document. When people describe the product in their own words, do they all use the same words? Are their radical differences in what they describe? If the answer is yes, back to the word processor. Schedule, number of man hours needed, and cost are good metrics to test.

Test the requirements. Do a review, walk through and formal review.

Put the requirements under change control.

Let’s Get Started

An upcoming post will be the requirements for the CarNet Player. Once that is done, we can start on the supporting documents, the design and implementing our vision. Stay tuned.

A last note
I am assuming most of my audience are engineers like myself. If you are, the next time you start a project, please get involved with the requirements. Volunteer to write them if you have to. At least try to be on the team. You’ll be making you life easier for the duration of the project.


(Editors note. I wrote a series of rants on requirements in a blog a friend and I were working on. It was called “Doug and Doug doing Embedded Design”. We have since taken it down mostly due to a total lack of interest from us and zero traffic. We did it to support a side project building a car mp3 system.

I am putting the rants here, because they are part of my development manifesto. I also need some easy posts as I am really busy for the next few weeks. I have edited the posts and tried to test links. If you see any issues, let me know.)

Building the product requirements

If we are treating this project like a product development effort, where do we begin? The answer in most companies is with the Marketing Requirements Document. Every engineer reading that last sentence just let out a groan of agony.
Don’t get me wrong, as an engineer I think marketing is hugely important. I have worked closely with some very good marketing people. If the marketing people you work with do not know all about this, you have bigger problems than just requirements.
But wait, Joel says we need a document. It is one of the 12 items in the Joel Test.
I can hear your argument being shouted back, “wait you fools! The 37Signals guys say don’t do it”
The truth, as usual is not black and white. Personally I lean towards Joel Spolsky’s way of thinking. You need some way to communicate what you are planning to build to everyone involved.
In the 37Signals case, there are few people involved. They do mock ups and design the UI of their applications before coding begins. That could be called the requirements, but they would object to the word.

In my experience the requirements process is always a failure. I have read and researched the topic. It seems to me that it should be very a useful and good thing to know what I am building before I start. As an engineer, I crave a detailed and complete requirements document. I am always been left hungry.
Why does Marketing get to decide anyhow? We are the engineers. We know what to build! We built the widgets that paid for the building they sit in. For anyone curious about the history, there was an article in the Harvard Business review titled “Marketing is Everything” by Regis McKenna from 1991. A book followed. If you read the article it describes the coming utopia of market driven companies and happy empowered consumers.
Alas, the practice is much harder than the theory.

Requirements are really hard

A recurring them on this blog and I have found in life is the fractal nature of reality. Requirements sound simple, write a document that says what to build. Requirements are an art and science in their own right. As we zoom in, the details are complex at any level.
There is a requirements convention and an IEEE society, plus many books.
Two of the best I have read are Exploring Requirements: Quality Before Design by Donald C. Gause, Gerald M. Weinberg  and Customer-centered products : creating successful products through smart requirements management / Ivy F. Hooks & Kristin A. Farry.
Anything by Gerald Weinberg  is usually worthwhile.

Why the requirements process fails

Here are some of the ways I have seen the requirements process fail. Doug and I will try to avoid these pitfalls in our simple requirements.

Marketing is not able

In the beginning, the founders get together around a great idea. There are few people around the lunch table. They throw out ideas and one is really good. It gets hashed out and everyone understands. They found a company and build the idea into a business.
Now after a while, it is time to build a new product. This will be a really new product, not an add on or update to the original. Of course, the founders sold out or left last summer to spend their dump truck of money they earned off the first idea.
The marketing people are now tasked with writing the requirements. Of course, they have never done anything like this before and no one on staff is a requirements expert. No one has read the books, so the time needed is underestimated. Read that last sentence again, it is the killer point.
Marketing is out trying to setup a time to talk to customers, get an NDA in place before they do, and not piss off the sales people. Because this takes much longer than expected, the engineers who were sitting in on the kickoff meeting get bored. Bored engineers are dangerous, idle hands and all that.

The Engineers know what to build

As engineers, we are industrious by nature. We go and gather our tools and begin to build something. Depending on how long the marketing group takes, we may be pretty far along.
When the document is delivered, deliberated at the highest levels in the organization, and passed down to the engineers the conversation goes something like this:
Engineer: :”We can’t do that”
Marketeer: “Why not?”
Engineer: “We never planned on that feature in the design.”
Marketeer: “Why are you planning and designing without the requriements?”
Engineer: “You took to long, it is always up to us to make up the schedule time, etc.?”
Marketeer: “What did you build?”
Engineer: “The same thing as last time, but we put a clock in it.”
Marketeer: “Arrrrggggg!!!!” Slam (Conference room door slamming and the sound of fading screams in the hall).

Sales is in the drivers seat, not marketing

This is the classic. The sales team does not want anyone grilling the customer about what comes next. If the customers know a newer, bigger and better product is around the corner, they will wait and not clear the old product off the shelf.
So, a smart sales persons says, “I talk to customers all the time, I know what they need, just ask me and we will get these requirements done quick!”. This is the sales person as proxy for the customer syndrome. As an engineer I have to say it is one of the worst syndromes a company can have.
Marketing talks to sales. Sales wants feature X. Feature X is big, ugly and difficult. A fearless engineer, lets call him “Doug” asks, “Why do you need feature X”. It goes back and back through layers and up and down the hierarchy. Finally the answer returns and it is always the same, “Customer A said they would buy $1 bazillion worth if we had feature X.” OK, now Doug asks “How much will they pay for feature X?” The answer, “Pay? no, they won’t pay extra for it.”
This time it is the engineer running through the halls with his underwear on his head screaming.

The customer says ‘whatever’

Once again the company goes out looking for feedback from the customers. When the customer finds out this is not even a real product yet, could get booted at any time, and will not be in their hands for over a year, they just don’t care.
Very few customers have time to tell you what you should be building. Usually they are busy running their own business. Yes, the product may be revolutionary and really save them money and make life easy. The fact that you still have to build it and they must wait is a complete turn off.
Even worse, if the customer realizes they have a need that your current product does not meet, maybe a competitor’s does. Or why buy now? Why not wait for version 2.0?
Most users don’t know what is possible. So it is very difficult for them to have an opinion about the next generation of your product. Most of the feedback is either completely impossible, costs way to much, or goes like this, “Just build the same thing as last time, but put a clock in it.”

Exactly how many customers responded to the survey?

Be very careful when you hear statements like “All the customers need this feature”, or “everyone we spoke to has to have it or they will not buy”.
The flip side of customer apathy is the over interested customer. If most people can not be bothered, there will be one who is more than willing to specify a product that meets their exact needs. Does it meet the needs of a larger market? Well, that is our problem, not theirs.
In more than one company on more than one occasion I have found that “all customers” really meant the one who we met. You can not do statistics with only one data point. Two is not much better. Unless you are selling to the government, there had better be more than a few customer contacts.

Requirements are just hard to get right

Most small and even large companies do not have a requirements expert. I have never actually encountered someone who has read the books I recommended above. Few companies will go to the expense of hiring a consultant, at least not at the beginning.
Most of us muddle through using one of the three methods listed above. Some poor soul is given the task of writing the actual document. It is unfortunate that the result is usually a document. A database or tool could really help.
The document is written in good faith as best as can be managed. It gets sent off to the engineers and immediately rejected. Meetings are scheduled and time is wasted going back and forth repeatedly. In the end, we build the same thing as last time, but put a clock in it. Sigh.
What went wrong? The engineers complain that the document was:

  1. not specific enough
  2. told us how to implement features, not what they were
  3. gave no priorities
  4. was too detailed
  5. had untestable requirements

In the back and forth some important things get dropped, the wrong ones get emphasized and it winds up being design by committee. A generic product is described that looks just like everything else in the market.
If no resolution can be found in the meetings, the project is thrown into development with orders to “just do it”. Maybe a consultant gets hired to sort it all out. See the section about bored engineers to see how this works out.
Rinse and repeat.

Parts two and three coming soon.

How to write Ashton Kutcher into “Two and a Half Men”

What this has to do with multi-core software I just don’t know. This came to me while brushing my teeth this morning. They were talking about it on the radio, so it must have seeped into my subconscious. Now I have to write it out or my brain will be stuck. Some friends know I rewrite sitcoms for fun, why I dunno. If you are not familiar with the changes in the show, they are explained here.

Obviously the writers of the CBS show Two and a Half Men have a problem. Lucky for them there are random people like me on the internet to help. I have come up with a plot that will work, and could be mined for comedy gold. The great fear of all fans is that Ashton will be a direct replacement for Charlie Sheen’s character. I have to agree. The problem is how to get him on the show, get Charlie (the actor and character out) and not jump the shark.

First let’s get Charlie off the show. This is actually simple. Do not do it soap opera style and kill him off, only to lamely resurrect him later. Instead use the now classic sitcom gimmickry, and make Charlie the character we only hear from and never actually see. The character Rose (played to perfection by Melanie Lanskey) is the key. Charlie realizes she is the only woman he has ever really had a long term relationship with, and they go off together to Europe. Now we, and Alan (Jon Cryer) sort of know that Rose probably has Charlie drugged and tied to a bed someplace, but Alan gets to move upstairs in the Malibu beach house,  drive Charlie’s Jaguar, plus keep Berta and all expenses are paid. The setup episode involves Rose announcing all this, Alan going to save his brother, then picking up a beautiful woman in the Jag. He decides Charlie is probably happy with Rose.

Now Charlie can send in a weekly postcard from various spots around the globe. If Charlie Sheen decides he needs a paycheck signed by CBS, he just shows up. No need to revive the dead!

With just Alan in the house, things would get dull fast. CBS WRITERS DO NOT MOVE JAKE INTO THE BEACH HOUSE. Having Jake and Alan live together does not make for good comedy. The whole cast has to get involved for the most fun. But, Alan has to have a roommate, or things get dull. No, not Ashton either.

Jake has to stay in Judith’s house. We should put him into culinary school, so he is racking up bills for Alan, not leaving the house, having kitchen mishaps, and meeting girls from school. There is lots of material right there with his friend (Graham Patrick Martin) in tow it is all fun. It gives a reason for Alan and Herb to go places with the kids, interact with Judith, and sets up plot after plot.

I have always thought Ryan Styles as Judith’s (Marin Hinkle) second husband was, one hilarious, and two not used enough. He held up well on The Drew Carey show, so lets move him in with Alan. The plot is simple, Judith throws him out, he knows Alan is the happy Jaguar driving bachelor in the beach house, so he shows up on the door step. The whole tension over the paternity of Judith’s daughter is good for at least three episodes, plus a nice running joke. It may be fun to have Herb meet gorgeous women, while Alan still can not win.

Now, we never really see that daughter. This must be handled carefully. Yes, the cute kid is a sure sign of shark jumping, so casting is important. The kid should be cute, but has to be believable as Jake’s (Angus T. Jones) little sister. She should be cute, but not too cute. She can share his huge appetite, but be really sharp. A bit more Judith, less dense. Think a young Mayim Bialik, and it will play better than a super cute kid.

What about Grandma? Holland Taylor as Evelyn Harper is absolutely perfect. She shows up, worries about Charlie, but does not do anything about finding him. She eventually gets a clue about Judith’s daughter. Jake is her favorite, then everything flips and Jake can not figure out why. That is one episode I am giving away for free. She shows up, gives Alan a hard time, has a strange, uncomfortable relationship with Herb. Maybe have them wake up in the same bed after a wild night. All good stuff.

Now, where do we put Ashton into all this. (You thought I forgot him.) It is obvious. Ashton can not play a Charlie replacement. He can play himself, the sort of doofy, good looking, younger lover. Yes, he should be Judith’s new love interest. He plays the Ashton character that will feel familiar, but keep some twists so no one gets bored.

Jake and his little sister hate Ashton’s character, of course, as do Herb and Alan. Why wouldn’t they? While Judith is smitten, Ashton makes Charlie look like a choir boy. He chases anything in a skirt. The kids catch on, eventually after some close calls. Then they can plot to get him caught by Judith. Here is the twist, he acts dumb, but is really pretty smart. He is not going to let anything stop the good thing he has going. He is living with Judith for free, totally financed by Alan and Herb. Ashton can use the Malibu house for his hook ups, trying to weasel the use of the Jaguar, and to get the kids. He can find out the daughter is really Alan’s, and tries blackmail, but has to be careful. If Herb finds out, he can get out of alimony to Judith and the free ride ends.

It may even be fun to make Ashton’s character a teacher at Jake’s community college culinary school. That gives him some power to manipulate Jake, but he still has to be careful. Everyone is living a bit of a lie, Herb is paying to support Judith, and Ashton, plus his daughter (if she really is his). Anything to upset the balance and stop the funds will unite the enemies.

Add a bunch of beauties stopping by periodically looking for Charlie, and the fun flows free.

The key is to not dump all this in one season premier. There is a full season just to get through the setup, then a season to let plots play out. We really don’t need a cliff hanger ending until the end of Ashton season three.

So, what does this have to do with writing software for embedded systems. Let’s say if one part of the system starts acting crazy, you may have to rearrange the circuit to make it work. How’s that?

If I get some comments, I will reveal my super secret soap opera twist, and the cliff hanger for Ashton season three.