How to Write a Software Request So the Developer Builds It Right the First Time

published: true

"Hey, can you build me an app that tracks my leads?"

That was the whole request. One sentence. And it sounds reasonable — until you try to actually build the thing and realize that sentence just handed you about fifty decisions and answered exactly none of them.

What's a lead? Where do they come from — a web form, a phone call, a text? What fields do you want stored for each one? What happens when one comes in — does an email fire, does it write to a database, does it just sit there? Who's the user — just you, or a whole team? Is this a mobile app, a web app, or a script running in the background? What does "tracks" even mean to you?

None of that was in the sentence. So whoever builds it is going to fill in every one of those blanks themselves — and they're going to fill them in with whatever's easiest for them, not whatever's right for you. Then you'll look at the finished thing and say "that's not what I meant," and they'll say "that's what you asked for." And you're both right. That's the whole problem.

Vague feels fast. It isn't.

People keep requests short because they think they're saving time. The thinking goes: I'll give them the gist, they'll figure out the details, we'll sort it out as we go.

Here's what actually happens. The details don't disappear because you didn't mention them. They just get answered later — by the developer, mid-build, after the budget's already half spent. Every question you don't answer up front becomes a guess. Every guess that's wrong becomes a rebuild. And rebuilding is the most expensive thing in any software project, because you're paying to code it, paying to discover it's wrong, and paying to code it again.

The questions are coming either way. The only choice you have is whether they get answered before the work starts, when changing the answer is free — or after, when changing it costs you.

Describe the outcome, not the solution

The biggest mistake I see is people requesting a solution when they should be describing an outcome.

"Build me a dashboard with a calendar view" is a solution. You've already decided the app needs a dashboard and a calendar, and you might be wrong about both. Now the developer is locked into your guess instead of solving your actual problem.

The outcome is what you're really after: "I keep double-booking jobs because I can't see at a glance what days are already full." That is useful. Now the developer can tell you whether a calendar is the right answer or whether a simple availability check solves it. You hired them to know that. Let them.

A good rule: describe what should be true when the software is done, not what the screen should look like. "When a lead comes in, the app texts me within a minute so I never have to remember to check anything." That one sentence tells a developer more than three paragraphs about buttons and layouts.

What a request that actually works includes

You don't need to write a novel. You need to answer the questions that would otherwise get guessed. For almost anything, that's:

Who the user is. Just you? A team? Your customers? On a phone or a desktop browser? Someone comfortable with software, or someone who needs it dead simple? This single answer changes the entire build.

What they're trying to get done. The actual goal, in plain words. Not the feature — the job the feature is supposed to do.

What happens, step by step. Walk the developer through the flow like a story. "A customer submits the web form. Then the data writes to a sheet. Then a text fires to me and to whichever driver is closest." Each "then" is a decision you're making instead of leaving to chance.

The inputs and the outputs. What data goes in, and what comes out? Name, phone, and address in — a sorted list and an SMS alert out. Be specific about the pieces of data.

The edge cases. What happens when two leads come in at the same second? When a required field is left blank? When the same lead is submitted twice? You don't have to solve these — naming them forces the conversation now instead of surfacing it as a bug later.

What "done" looks like. People skip this and it's the most important line in the whole request. How will you know it works? "Done means I can submit a test lead from my phone and the text shows up on mine within a minute." That's an acceptance test — now there's no argument about whether the software is finished. You can check it yourself.

What it is NOT. Just as important as what it is. "It doesn't need to process payments. No user accounts or logins. Just capture the lead and send the alert." Saying what's out of scope stops a small tool from quietly ballooning into a platform — and stops you from paying for features you never wanted.

Bad request vs. good request

Bad: "Build me an app to manage my leads."

Good: "I run a one-man landscaping operation. Leads come in two ways — a form on my website and phone calls I jot down. Right now they live on scraps of paper and I forget to follow up. I want a simple web app, used only on my phone, that puts every lead in one list sorted by who I haven't called yet, and texts me a reminder to follow up after three days. Done means I can add a lead in under thirty seconds and never lose one. No invoicing, no customer logins — just capture and follow-up."

Same project. One of those gets the developer to the right thing on the first try. The other gets you three rounds of "not quite" and a bill to match.

This is most of the job

When someone sends me that second kind of request, I can quote it accurately, build it once, and ship it without a dozen back-and-forths. When someone sends me the first kind, the first thing I do is ask all the questions they didn't answer — because I'd rather spend an hour writing a clear spec than three weeks coding the wrong app.

That's the whole reason I work in fixed quotes at 928 Builds. A fixed quote only works if both of us actually know what's being built. It's the thing that protects you from surprises and protects me from building blind. A clear request is the cheapest insurance in the entire project.

You don't need to know how to code it. You just need to say clearly what should be true when it runs.

Spend the hour writing it down. It buys back a week of building.

Tags: software, webdev, programming, productivity

Joel Bennett · Founder, 928 Builds · Tucson, AZ · 928builds.com