Maps and Plans

Every journey goes more smoothly with a map of some sort. Whether it’s a trip to Antarctica or developing firmware for a new microcontroller-based device, it helps to know where you’re going. Without a clear definition of the destination it’s tough to know when you’ve actually arrived. It is also helpful to know what it is, exactly, you expect to find when you do finally arrive.

For engineering, be it mechanical, electrical, software, or some other form, the destination is defined by the requirements, and the project plan lays out the map to get there. Alright, I can hear the groans now. Yes, I know, many people do not like dealing with plans and requirements. Many engineers avoid writing these sorts of things; I’ve even seen situations where an engineer quit a job because the need arose to write a development plan, requirements, or test documentation.

In the end, it is usually how well a project is defined and planned, how well the requirements are specified, and how it is tested, that determines if it will succeed or fail beyond the makerspace or home shop stage. I don’t know for certain, but I suspect that Hewlett and Packard didn’t have a whole lot in the way of detailed specifications and requirements when they built their early prototype test instruments in a garage in Palo Alto, but I know for a fact that it didn’t take long for them to adopt and apply those concepts to their growing company. If they hadn’t created requirements, design plans, and test procedures I don’t think that we would have seen any Hewlett-Packard signal generators and oscilloscopes in labs and shops around the world.

OK, so these things are important, but how much do you really need? Is it possible to create something useful without writing hundreds of pages of coma-inducing text?

Yes, it is! I’m going to tell you the secret for creating simple design plans, useful requirements, and easy test procedures.

First off, the plan. This one isn’t hard at all. It basically answers the following two questions: What do you want to design and build, and how do you intend to do it? If you can describe it to your friend or significant other, and they can understand it, then you’ve created a project plan. In many cases it doesn’t have to be any more technically detailed than that. Of course, it depends on what you want to build. Something like a computer-controlled windowsill herb planter really doesn’t need 200 pages of description, but a rocket engine is going to need a lot of detail. Then again, if you’re working on rocket engines then you should already know about all this, right?

Now, the requirements. The one or two (or maybe three) pages of the project plan just paint the end result in broad strokes (“build a computer-controlled windowsill herb planter”), but it doesn’t give any low-level specifics. That’s not what it does. That’s what the requirements do.

Requirements define specific features, characteristics, and capabilities, all of which together define the end result. You might think of the plan as a slightly fuzzy image of the final result, and the requirements pull the image into focus and bring out the details.

The details are things like: How large is it? How heavy is it? How much can it hold? How will it be controlled? How will someone interact with the control system? What are the time, volume, temperature, pressure, or voltage constraints? What should happen if something doesn’t work right? Some of these are functional requirements, some are physical requirements, and some might be safety requirements. The secret to discovering requirements is to play “What if?” with the thing described in the project plan. What if it’s too large to fit into the intended space? What if it’s too heavy to be practical? What if it requires more power than can be safely delivered? What if someone enters the wrong control parameters? What if a rainstorm happens to come along or a pigeon deposits something unpleasant on the electronics? And so on.

It doesn’t take very long to come up with a list of things the final design must do, and it can actually be a fun challenge to capture a good basic set of requirements. But again, it doesn’t need to be a huge set. The important thing to keep in mind is how critical the requirements are to the function of the device or system. To do that I like to take a starting set of requirements and then work through them with an eye towards throwing non-critical requirements out. If a requirement really doesn’t matter in the end, then it probably shouldn’t be a requirement.

Lastly, an important thing about requirements to keep in mind is that each one must be testable or verifiable. If a requirement can’t be tested or somehow verified, then it’s not a good requirement. It’s a desirement, and those sorts of things are open to subjective interpretation. So don’t worry about subjective things like color unless you are prepared to find some way to verify the reflected wavelength of light from a painted surface. Characteristics like voltage, current, frequency, weight, size, power dissipation, response time, flow rate, and volume can be easily and definitively measured, so they can be requirements that can be tested.

Which brings us to the last part: Testing. You’ve created a nice short project plan (maybe even with some concept drawings or CAD designs), and you’ve created a set of requirements to use when building the thing described in the project plan. You’ve built the first prototype, and it doesn’t smoke or explode when it’s powered up. Great. But how do you know it does everything it’s supposed to do? Does it do it correctly and reliably? Does it handle off-nominal situations in a graceful manner? You won’t know for certain until you test it, and to do that you will need some kind of test plan. Testing without a plan is perhaps worse than no testing at all. If something isn’t tested you know it can’t be trusted, but if it’s tested badly one might assume that it has been adequately tested when, in fact, it has not. Software developers are all too familiar with this type of situation.

Ideally a test plan is derived from the requirements. For each requirement there must be a way to test or verify that the requirement has been met. This correspondence between requirements and tests is referred to as “traceability”, meaning that each test case can be traced back to a specific requirement. A test case describes the test scenario based on a requirement, and it has a corresponding test procedure that gives the step-by-step process for performing the test. In some cases these are combined into one test description, and in other cases (such as aerospace, for example) you might find a binder full of test cases and a binder with test procedures. This is a reasonable way to do things if you happen to have a test department that just does the “connect this, push that, measure something else” activities, but for small projects it’s rather pointless.

For example, if there is a requirement that states:

The over-voltage trip circuit shall engage within 2 milliseconds of detecting an over-voltage condition.

Now, we’ll assume that the over-voltage trip point is either specified in some other requirement, or it is something that can be adjusted. We can test this requirement with the following test case:

With the unit active and operating nominally, apply a voltage to the over-voltage trip circuit and observe the trip circuit response. The system power should be disconnected within 2 milliseconds of the occurrence of the over-voltage condition.

A test plan (or another paragraph of the test case) would then describe what measurement tools to use, how to supply the necessary voltage, and how to record the results. Granted, this is a somewhat contrived example, but I think you get the idea. For every requirement there needs to be a test that verifies that the requirement has been met. The tests could be as simple as a checklist (DC power? Check. LCD display working? Check. And so on, and so forth), or it could deal with specific values for voltage, current, time, or whatever parameter needs to be verified to satisfy a requirement.

In the end you will end up with three small stacks of paper (if you’re into paper, that is): The project plan and design description, the requirements, and the test plan. Congratulations. You’ve just made the first step towards a repeatable and verifiable process. If you happen to discover that the requirements are incomplete, then you can add to them. If there is a design problem it can be addressed and the resolution incorporated into the documents. And if anyone ever challenges you to prove that your design works as described, then you have the test results to prove it.

Just having some basic plans and requirements in place will help to insure that each subsequent thing built using these documents will look and act like every one before it. If you only build one of whatever it is, then you will at least have something you can share (or sell) if someone else wants to also build one. If you want to build many things then you can be reasonably confident that each one will behave as intended.

I’ve only skimmed the surface here when it comes to project plans, design descriptions, requirements, and test plans. You can always dive into some good books on the various topics, and there is a large amount of free information on numerous web sites. But the point here isn’t about creating weighty tomes full of cryptic jargon and lots of “shall” statements. The point is to write just enough to know where you want to go, how you plan to get there, and how you will be able to know for sure when you have arrived.


0 Responses to “Maps and Plans”

  1. Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Follow Crankycode on

Little Buddy

An awesome little friend

Jordi the Sheltie passed away in 2008 at the ripe old age of 14. He was the most awesome dog I've ever known.


%d bloggers like this: