Skip to content

Delivery

Software requirements: the one page you need before a vendor call

Write five answers on one page and send them to the firms you're considering. The long specification can wait for their questions.

Computing America. Applications, integrations, data analysis and AI/ML engineering.

Send the page
3 min readComputing America
One sheet of paper on a long conference table, a tall stack of unopened binders pushed to the end.

In short

  • A requirements document written before any technical conversation fixes decisions when you know least. The delay it causes is the smallest cost it carries.
  • One page is enough to start: the trigger, who does the work today, what it costs when it goes wrong, what must not change, and how you would know it worked.
  • A long specification doesn't transfer risk to the vendor. When the system misses the need, you still lack the system.
  • Detail is not the same as precision. “The report runs nightly” is detailed; “the report is wrong if it misses an order booked at 23:58” is precise, and only the second one changes a design.
  • Hold the problem and constraints identical across bidders and compare what each says is hard.

Before a vendor call, write one page with five answers: what triggers the work, who does it today, what it costs when it goes wrong, what must not change, and how you would know it worked. A long requirements document written first is written when you know least, and the first conversation would have shortened it.

Fig. 1
  1. Group: The usual order

    Long document first

    Written when you know least

    • To Design fixed early
  2. Group: The usual order

    Design fixed early

    Solutions dressed as requirements

    • To Vendors price the list
  3. Group: The usual order

    Vendors price the list

    Each firm answers what you wrote, not what you need

  4. Group: The shorter order

    One page first

    Trigger, today, cost, constraints, success

    • To First conversation
  5. Group: The shorter order

    First conversation

    The vendor's questions are the deliverable

    • To Shorter requirements
  6. Group: The shorter order

    Shorter requirements

    Written afterward, by people who know what they are for

A long document fixes design decisions before any vendor has asked a question; one page first puts the questions ahead of the specification.

What the long document does

Writing it delays the project, and that's the smallest cost. It also fixes decisions early that would be better made late. Requirements documents are full of solutions dressed as requirements. “The system shall provide a dashboard showing X” is a design decision, made before anyone asked what question the dashboard answers or who will be looking at it at seven in the morning.

And it doesn't do the job people hope. A detailed specification feels like risk transfer: if it's written down and they miss it, that's on them. What it transfers is blame. When the system doesn't do what you needed, you still don't have the system, and now you have an argument too.

The page you actually need

Five things, written badly, in an email, are enough to start a real conversation.

  1. 1.What starts the work. A customer calls, an order arrives, a truck reaches a gate, a month ends. Software is mostly a response to something happening, so name the trigger before the feature.
  2. 2.Who does it today, and with what. A person, a spreadsheet, three systems and a phone call.
  3. 3.What it costs when it goes wrong. Not a feeling: an order re-keyed, a day of a controller’s time, a customer lost last quarter.
  4. 4.What must not change. The system you aren't replacing, the regulator, the customer who won't accept a new file format, the two people who won't be retrained.
  5. 5.How you would know it worked. One sentence, ideally with a number. If you can't write it, that's the most important thing to find out, and better now than at acceptance.

But we have to compare vendors fairly

A procurement process needs a common basis, and sending five firms five different conversations feels unfair and unauditable. The common basis doesn't have to be a feature list.

Issue the problem and the constraints, hold them identical, and let the responses differ. Then you're comparing what each firm thinks the real difficulty is. The one that spots a risk the others missed has told you something. So has the one that restated your document back to you.

FAR 11.002 asks agencies (opens in a new tab), to the maximum extent practicable, to state requirements as functions to be performed, performance required or essential physical characteristics. That leaves the bidder free to propose how. FAR 15.201 (opens in a new tab) encourages exchanges of information with industry “from the earliest identification of a requirement,” and asks that specific information given to one potential offeror reach the others no later than the next general release. Share the answer to one firm’s question with every bidder.

Send the page, then write the rest

Write the five answers today, send them to the firms you're considering, and judge each on its questions. They show whether a firm is listening, whether it has done this before, and whether it will tell you something unwelcome in the first hour or the ninth month. Write the full requirements afterward.

Sources

  1. 1.FAR Part 11: Describing Agency Needs (opens in a new tab), Federal Acquisition Regulation

Next step

Send us the page.

Five short answers, written badly, in an email. We will come back with what we would need to know next and what we would build first.

Reply
A person replies, not a sequence: within one business day, from someone who would be on the engagement.

Packages

Start with a package

Four packages, each with its price on the page. Pick one and buy it online.

Billing