Blogs

Requirements, Specifications and Tests

Kenny MillarJune 20, 2013

As a freelance developer of all things embedded, it's important that right through a project everyone involved knows what is expected, who is responsible for delivering, and how to confirm that what is delivered meets the customers expectations.

I have a tried and trusted method that works for me each time, is flexible enough to deal with feature-creep and solid enough to give the client that warm fuzzy fealing that they crave.

I've dound that this method of working has in the past been the thing that swings a contract in my direction, above the competition. And in fear of sounding like an american commercial, now I'm going to share it with you. Please feel free to comment and criticise! I know you will anyway....

Many of my clients have an idea for something they need or want, but have no idea how to run an electronics project - after all they are in the market of making doodahs and whatsits, not gadgets and gozmos.

So this is how I like to drive a new project.

Inception

First comes a set of requirements. This takes the form of a few emails and phone calls backwards and forwards with the client, but always ends up with a written document setting out what the clients requirements are. This is NOT a specification for the end product - this is a set of requirements. It sets out what the device will do, what it is for, who it is for and so on. This document has to be 90% driven by the client - but you as the engineer can help him write it by giving the benefit of your vast experience, after all, only the client knows what they want, what they really really want. Your job at this stage is to get it out of the clients mind and formalized in a document. This document is probably the most important one you'll get. We'll call it the 'Set of Requirements' from now on.

Giving birth

The document from step 1 gives birth to two separate documents now. One of them you'll porbably find you can't wait to get your teeth into, the second one, pah, get someone else to do it. ONLY JOKING! The 2nd one is very importany for getting your final pay check for the project - here they are.

The first of these new documents, which you will draw up, is the Technical Specification -  this sets out HOW the device will achieve all of the things in the Requirments. It is the specification from which you will later start the design work. It sets out things like the User Interface, the connectivity, the PSU, maybe the processor and the other hardware. This document is 90% driven by YOU the engineer. With a well written technical spec your design work will be easier and some of feature-creep can be swept up at this stage. Show the specifications to your client often. We'll call this the 'Technical Spec' from now on.

The second new document - and this is important - comes from the Set of Requirements NOT from the technical spec. Read that again, this is where most people make a mistake and get it AFE(*1). The second new document comes from the Set of Requirments NOT from the technical spec, and it is this: The QA Test set. This is a set of tests whose purpose is to ensure (and to prove) that the product you deliver meets all the requirements. It is NOT designed to ensure it meets the technical spec. The document sets out how the customer will test the product to ensure it meets their (documented) requirements. It sets out tests that a QA department could use, (if there is one), or that the client can easily follow. It's is imperative that it tests the product against the Requirments and not the spec. It is also better wherevere possible that the people doing the tests have access to only 2 things: i)The Set of Requirements and ii)The Product. Wherever possible the people carrying out the tests should NOT have access to the developers or the technical spec. Their job is to check the product against the requirements and report back. Lets call this document the QA Test Set from now on. You could think of them as 'Final Acceptance Tests' but they will also be used during the lifecycle of development.

At any time if there is a change to the requirements it should be reflected in the QA Test Set. Changes to the Set of Requirments should only be driven by the client. If during development you discover that one of the requirements is undeliverable you do not just alter the tech spec and the QA Test Set, you go back to the client, explain the situation and they change the requirements which triggers and update to the tech spec (possibly) and the QA Test Set. It's best if the QA Test Set is drawn up by the client rather than the engineer, but they may need help to do so if they have never done so in the past.

If your product is to be delivered in key stages, make sure that there is a QA Test set that covers each stage. You must be able to test what you deliver against what the customer is expecting at that stage. Many issues which can have major headaches later can be avoided by having a clear QA Test set for each stage of delivery. It doesn't need to be complex, but it does need to cover that the client is expecting at each stage.

DESIGN

With an agreed Set of Requirements and a technical spec you can begin your design. At every step check that your design is still within the requirements and keep in mind the QA Test Set - someone will be running those tests against your product one day soon!

As design progress often you'll deliver some interim prototype to the end user, and often at that stage they'll casually mention that if it can do ABC maybe it could do D and E too? Make sure you get D and E  into the set of requirements as an 'update' or 'ammendment' and reflected in the QA Test Spec - there is nothing worse than getting to the end of a project only to find one key funtion the client mentioned in passing has slipped from your mind.

All along you need to have your own set of unit tests, whether they are software unit tests for the embedded code, or hardware unit tests - are you SURE that interface is driving the signals to the correct level? How do you know - beacause you tested it! Your unit tests should be documented, with results recorded - even if it's a simple spreadsheet. These tests are important they WILL save your bacon one day when you realise early on that you have overlooked a simple piece of the design and caught it before getting 100 samples made.

When you are ready to deliver the product, run through the QA Test Set yourself first, so YOU can have that warm fuzzy fealing that it's going to pass their tests.

SUMMARY

To summarize this, the SET OF REQUIREMENTS is agreed by you and the client, but driven by them.

The SET OF REQUIREMENTS produces and QA TEST SET - the client owns both of these.

You draw a TECH SPEC from the SET OF REQUIREMENTS and a design from the TECH SPEC

Any changes (feature-creep or otherwise) must be reflected down from the top, ie from the Set Of Requirements, and go through to the QA Test Spec.

Wherever possible a non-engineer should carry out the QA Tests. QA Testers should not have access to the tech spec or engineers if practical. 

I hope this has given some food for thought. It works for me and has been a good basis for a great career in electronics. I should keep it a secret really, it helps win customers.

At the end of the day, the client pays the invoices and when they have a warm fuzzy feeling that they can confidently show off your product to their board, they pay the bills much quicker. 

(*1) AFE = 'Arse for Elbow'



To post reply to a comment, click on the 'reply' button attached to each comment. To post a new comment (not a reply to a comment) check out the 'Write a Comment' tab at the top of the comments.

Registering will allow you to participate to the forums on ALL the related sites and give you access to all pdf downloads.

Sign up

I agree with the terms of use and privacy policy.

Try our occasional but popular newsletter. VERY easy to unsubscribe.
or Sign in