How To Tell A Software Developer What You Want

Any business user who needs the help of a software developer -- to build a website, say, or to create a custom application -- needs to explain just what it is she needs and wants. Judging by the results, however, the communication is far from flawless. Clients and users often grouse about those irksome designers and programmers who delivered something far different from what was desired, which is how we end up with sites as popular as Clients From Hell.

It doesn't have to be this way. If you explain to your development staff or outside consultant what you want, in the right manner, you have a good chance of getting your project done on schedule and on budget -- with results that you love. These six steps can ensure the best possible outcome.

[ See also: Career advice: Making your mark in software programming and Programming magic: Rituals and habits of effective programmers ]

1. Define the business need.

The most obvious advice is to carefully explain what you want. But that assumes you know what you want, that you can articulate it in a useful fashion, and that you can keep your eyes on the objective. "If you don't know what you want when you describe it to us, it probably won't be what you expect when it is delivered to you," says programmer Paul Giegler.

Start at a high level: What is the goal? Write down your overall objectives. Think of it as a project mission statement.

Before you even call a software developer, says Saeer Butt, senior software architect at Zaphyr Technologies, "Finalize the goal that this software will achieve once it's completed, such as 'Reduce invoice-generation time by 30%' or 'Increase teller output by one hour a day.'"

John Simpson, director of customer outreach at Jama Software, recommends users force themselves to articulate the goal in 100 words or less. "Developers are good at executing details but they do even better when they have visibility and context to the larger vision," Simpson says.

This exercise helps your developer, but it's also good for you and your business team. If you start with a clearly articulated goal, you can easier measure whether the software fulfills the promise. Try to include a metric for success in that goal, as in the examples above.

2. Don't tell the developer about the solution. Describe the problem.

Once you've identified the overall goal of the project, get specific. What does the software need to do?

"Describe to the developer what problem you need to solve, and trust her to help you find the right solution," says Veronica Yuill, joint owner of web development company Archetype Informatique, based in the south of France.

Don't try to speak in the developer's language. Use your own business terms; just be prepared to define them.

It is a huge temptation to define a specific technology in your software requirements document. Resist that temptation. It becomes an unnecessary limitation and, sometimes, a trap.

For example, says Kevin Dwinnell, director of product and marketing at Brand Thunder, which creates interactive browser themes, a user might specify Flash animation. Instead he should say, "animation on the web page." Dwinnell says, "The other requirements will help steer development to the right solution, which could be Flash, JavaScript, animated GIF, or something else."

Rather than try to guess at the "right" technology that the developer should use, put your energy into being specific and eliminating ambiguity. "The more general the phrasing of the request, the more likely the product delivered is not going to match the vision," says Dwinnell. "I can ask for an 'easy registration process,' but I might get [a registration form] that is three pages with more information than needed. If I ask for a registration process limited to one page that collects name, e-mail address, and password, then I'm more likely to get that 'easy' registration I was seeking."

Make a list. Make two lists, in fact: Must-have features (requirements) and desired features (nice-to-have). Describe your problems, not the solution you expect. When it comes to prioritizing, later, this will help you distinguish between what you need and what you want.

Be as specific as possible. "The developers base their work on what you tell them. The more incomplete the instructions you give, the more incomplete the software you get as a result," says George Otte, owner of Geeks On Site Computer Repair, who learned this lesson the hard way. For some time his company was unable to use the Payroll function of its software tool, because the developers hadn’t been informed that Geeks On Site technicians get paid on a quarterly, not hourly basis.

Don't hide uncertainty. If a developer understands that you don't know what you want in one functional area, she'll be ready to help you explore the options. That's better than an arbitrary requirement. "If you don't have a clear vision of your project, work with user experience (UX) experts to craft your vision before you begin programming," says Smitty Smith, a developer at IdentityMine. "You will save time, money, and headaches in the long run."

3. Define the users.

Software isn't written for "anybody." It's written to serve a certain type of person who is assumed to have (or lack) specific knowledge. Write down who you expect will use the software; often, there are many types of users. Each user type (which developers sometimes call a "persona") needs a sentence or two to describe the information one can assume about the individual.

"These are not 'markets' or 'industrial buyers' but people who will actually use the product," explains Tom Cocklin, user experience designer and a human factors engineer. "What do the personas want to do and why?" For example, you might intend to create a website to sell garden supplies. Two personas have different needs: a loyal knowledgeable customer and a novice incidental customer.

At this point, you can begin to describe what needs to happen; developers call these "user stories." This clarifies the roles or personas and helps the developer approach a solution. As Robert Merrill, an independent consultant in Madison, WI suggests, write: "As a ______ (role), when ______ (business event) happens, I can __________ (do operation) with the software, so that ________ (reason why)." You'll have many of these sentences.

4. Document the existing workflow.

Many users are comfortable explaining what they want, but they miss the next important step: Explaining how the business problem is addressed now.

"If you can document the business process that needs to be automated, you will be forced to think about all the aspects of the business," says Butt. "If you can't document it, how can you instruct anyone to build it?"

Just about every application (in software and the real world) manages data and changes it in some manner. Web developer Laurie Grant recommends you consider, "What is the data you will be working with? In what form does it come into the application? In what form does it go out?" For example, she says, a shopping application needs a catalog, a way to pay, a way to give a receipt. "You need a flow to understand how the information should work. This is the process of how the business need is conducted," Grant says. Using this workflow, you and the developer can work out the pages or screens needed.

Use graphics and diagrams if they help get your point across. "Our favorite client had a Web document with screen shots and detailed descriptions of what happened on each screen, how each button worked, etc.," says Brad Waller, VP of business development for EPage. "That gave us a great starting point which we used to develop from."

Dean Cycon, CEO of Dean's Beans organic coffee company, has learned through several website redesign projects that it's best to make his own flow charts for his site's best processes and navigations rather than leave it up to the developers. "You always have to keep in mind that they are working for you, and that they have to give you what you want -- not what they think you need!" he says.

"Whenever possible, use real examples to communicate specific application functionalities or processes," says Jared Franklin, CEO of Chase Technology Consultants, a Boston, MA-based recruiting and placement firm. "For example, if you like how ESPN.com manages their customer forms and inquiry follow-through processing, then direct the software developer to this website and walk them through what you are referencing and would like for your site to involve." Don't expect your own application to look "just like" your example; use these examples as a way to communicate your needs and wants.

Think about every step of the process. What happens when things fail? (If you must micro-manage, write the error messages.)

5. Distinguish between user interface, platform, and content.

When you want a software application or website, it's all one big project to you. But developers see important differences, enough so that they have separate roles for each type of task. While the wording may differ, the big distinctions are the user interface (usually the visible part, such as what you see on a web page), the back end or platform (where all the calculations are made, and the data managed), and the actual data (which developers often call "content").

Let's say you want to buy a car. When you go shopping, it helps to be aware of the differences between the styling (sports car, red, shiny), the engine and other hardware (everything under the hood), and the forces that makes it go (gas mileage, who'll be driving the car). You may not care about all of these issues with the same intensity; just recognize that they are different. One choice may influence another; if you have a business requirement of "a vehicle that can haul a load of firewood" it affects both styling (such as size) and hardware (a big enough engine). You may never personally look "under the hood" of your new website, but your business requirements can affect the choice of that engine.

"In software design it's important to know both 'what it should do' and 'what it should look like,'" points out Rick Wayne, senior systems programmer at the University of Wisconsin. "Most normal humans are hardly aware of the difference, but for a developer building her plan of attack, the two are quite distinct." Unless your developer knows your subject as well as you do, it's more important to communicate the details on "what it should do." "Everyone on the business side knows minimum stocking levels vary from vendor to vendor - of course they do, it's obvious!" says Wayne. "But the developer might not get that, and fail to build in that crucial bit of flexibility until it's late (and expensive)."

So when you make your list of "What I want," it can help you and the developer if you separate requirements into functionality (what the software does) and user experience (how it looks, works, interacts with people). If relevant, you can include a section about technical needs and limitations ("It must integrate with our existing point of sale software, which is based on Microsoft SQL Server"), because that can affect platform decisions.

Don't go so far overboard in describing what you want that you micro-manage, but do be explicit about the things that really matter to you. Brad Waller remembers an early client who argued over the shade of blue his team used. "I'd guess our hourly rate was cut by a good 25% because we did not have a spec for the color scheme," he says.

Don't forget the data and other content that your application uses. Identify where the content is coming from. Who's writing it? In what form is it, and what will it take to get it ready for the new application? Who supplies the graphics? When will they be ready? Entirely too many projects have been delayed because of a missing logo.

This also means that you need think about your needs after the application is created. Who will administer it? How will it be updated, and by whom? How will it be backed up? What knowledge does that individual have? If you expect the developer to host and run the software, that usually is a separately negotiated item.

6. Prioritize.

By this point, you probably have a long wishlist. As with so many other things, you may not be able to afford everything on the list.

[ See also: 5 reasons to take a phased approach to software development ]

You need to prioritize and separate the "must have" from "want to have" from "It would be nice."

Show the entire list to your developer, with the priority items clearly marked. "In some cases, a requirement which may seem minor [to the user] may take several hours or days," says software engineer Jeanine Swatton. "It is a priority to us since it is on the priority list." Be clear about what is necessary. "If they realize a small feature will take several days, they are more likely to remove the feature entirely or give it a lower priority," she adds.

But recognize that it's just the starting point. The developer will think of things you didn't. That's what you pay for. If a developer suggests that you build in extra security features, it's probably because you need them - or at least you need to ask why she thinks you need them. As Giegler says, "Listen to your developer. If he says 'That isn't possible,' 'I'll need more time,' or 'That isn't in the budget,' it is most likely true."

Conclusion

This article only covers how to tell the developer what you want. It doesn't go into detail about how to choose the right developer, how to make the software development project succeed, or the likely problems you'll encounter.

It should, however, help you clearly define and communicate your software requirements - the first step towards success. As developer Kee Nethery says, "The more you can specify in advance, the more likely the software will come back more like what you envisioned and the more likely the cost will be affordable."