Building Widgets: Business Requirements vs. Technical Requirements

Have you ever built a widget? No, I’m not talking about one of those Mac OS X Dashboard Widgets, as cool as they are. Nor a Confabulator Widget, or a Yahoo! Widget. I’m talking about a good old-fashioned widget.

What’s that, you ask? Surely you don’t need me to explain a widget to you.

Oh, OK. Fine.

Actually, a widget can be anything. A widget something made out of something that does something. Happy now?

Software people build widgets all the time.

The key property of widgets is that they are a small, defined ‘device’ of some sort, built for a single purpose. It may be to pass data from OmniCom International to Global Amalgamated Worldwide Design, or it may just be to make fart noises.

Either way, widgets – and all other software – need to have requirements documented before they are built. (Actually, there is some debate as to whether a widget whose sole purpose in life is to make fart noises needs to have its requirements documented, but we’ll pretend it does.)

What many people don’t know is that there are two types of requirements: ‘business requirements’ and ‘technical requirements’. This article explains the difference between the two, and who should write which one.

Business Requirements tell you what a product is supposed to do. For example, “The widget needs to have the capability to make a randomly generated fart noise when clicked.”

Business requirements should generally be written by someone who understands the needs of the users of the software. Generally, these people have titles like ‘Product Manager’ or ‘VP Product Development’.

In some situations, it can actually be advantageous to have somebody that does not know how to code write these requirements. I can already hear the shrieks from the engineering teams out there, but hear me out: when you have these sorts of people write requirements, you often get a lot closer to the needs of the users, because non-coders don’t stop and think ‘Oh, that will be really hard to code, so I won’t put that in’.

Of course, such people are also more likely to put in requirements that can’t possibly be filled, such as this gem from a product manager in a previous life: “The software shall be able to interface with any database ever made” (Yes, this was a real request).

• Keep business requirements simple, clear and concise. Simple sentences like ‘the application shall email the customer after they have placed an order’ is often enough. You don’t need to specific every last field on the email, or if you do it might be better to do it in a mockup (graphical form) rather than with the written word.
• Don’t go overboard on detail. Its tough for some people not to go into a lot of detail, but if you do you may lose people.
• Use lots of pictures, diagrams and (if you can) screen mockups. Even if these are just done in PowerPoint, it’s better than nothing.

I’ve written a whole article on writing business requirements, so you might want to check that out too.

Technical Requirements tell you how a product is supposed to do something. For example, “The widget must have a module to display a picture of a whoopee cushion and a module to play fart sounds. The sound playback module must be built using Macromedia Flash and use the Flash sound library to interface with the hardware.”

Technical requirements MUST be written by somebody technical. (Surprise!) This person might have a title of ‘Software Architect’, ‘Senior Developer’ or ‘VP Engineering’, and is likely responsible for making sure that the software is built properly. Formal technical requirements aren’t always a must, especially if your team is really small (e.g. two or three people), but I’d strongly encourage you to at least do some technical planning before sitting down to code.

Technical requirements describe how a product needs to do something, and generally come in two forms: how the architecture of your product should work, and how it should interface with other systems and software.

Architecture answers questions about what each module of your software does, and how they should talk to each other. In the Fart Widget example, we have two modules… an interface module that displays a whoopee cushion and a sound module that actually generates a fart noise.

However, unless you spend your life writing fart software, your architecture will be a little bit more complicated. A typical web application, for example, will have two or three layers: an interface layer to display pretty stuff on the screen, an application logic layer that does the crunching, and a database layer to store everything.

You may want to do this part visually, either in something like PowerPoint or with a visual modeling language such as UML. Be careful here, though: while doing architecture work is a good idea, doing too much isn’t. In most agile software development environments, everything changes every few months, and if you spend four months on modeling you'll be out of business.

Interface requirements discuss what your product needs to do to operate in its environment: e.g. It should be built in Java and run on Linux, Windows and OS X, or it should use the ODBC database abstraction layer, etc. In the case of the fart widget, we noted that it would need to rely on Mac OS X’s standard sound library to … ah… cut the cheese.

N.B. There are some who say that the architecture bits belong in a separate software architecture document. I’m not always a huge fan of this methodology, but if it works for you then use it.

• Remember there are two types of technical requirements: how the architecture of your product works, and how it needs to interface with other systems or software. You’ll probably want to do both at once, possibly in the same document.
• Use a lot of diagrams and visual aids if you can. They may take a little more time to create, but you’ll get a lot more buy-in. Don’t forget that there are templates and such to help you elsewhere on this site.
• Consider using a visual modeling language such as UML, but don’t let it bog you down.
• As with the business side, keep this simple. Let the engineer assigned to a module figure out how to make things work at the detail level – you just need to give them the big picture. If you go into too much detail, your company will be out of business before you even finish the plans.
• Make this a collaborative process if you can. Use whiteboards, or screen sharing software, or something similar and do a lot of the architecture work with as many of the engineering staff as you can. This will do two things: 1) get everybody on board with the plan for the architecture, and 2) produce a better architecture, since some will see things that others don't.

Happy Coding!