How to Read a Software Proposal

You asked for a price and got a document. Somewhere in it is a number, and the temptation is to find the number, compare it with the other numbers, and decide. This guide is about the rest of the document, because the rest of the document is the first thing the developer has made for you, and it shows you how the project will go.

A proposal is evidence. Read it the way you would read a contractor's drawings before a renovation: not to check whether you could have drawn them yourself, but to see whether they show your house. Three questions do most of the work. Does it show that they understood your problem? Does it say what done means? Does it show you how you will see progress? Those three questions are the three stages we run every project through, and they make a fair test of anyone's proposal, including ours.

The seven steps below follow from them. The first three take the questions one at a time. The next two cover the parts of a proposal that only matter after you sign, change requests and the handover at the end, which is where the differences between developers hide. The last two turn the reading into a meeting: the questions to ask, and a checklist to bring to the table, so that before you sign, you can feel confident that you and the developer are describing the same project.

1. Alignment before building
2. Clear definitions
3. Visible milestones
4. Change requests and scope
5. Warranties and handover
6. Questions to ask
7. Checklist

Alignment before building

Does the proposal show that they understood your problem?

A proposal that opens with the developer's tools is telling you what they want to build. A proposal that opens with your problem, stated in words you recognize, is telling you what they heard. Look for:

• Your problem in your words. The symptom you described in the first meeting (the Sunday-night spreadsheet, the double bookings, the three systems that disagree), not a generic category it belongs to. If you cannot find the sentence you said, they may be proposing the software they already had in mind.
• Something they learned that you did not say. Discovery should turn up at least one thing: a step your staff take that you never mentioned, a report nobody reads, a rule that lives in one person's head. A proposal with none of this was written from the brief alone.
• Who will use it, and when. Named roles at named moments. "The dispatcher, at seven in the morning, before the first truck leaves." Software described without users is software described without a reason.
• What it is not solving. A good proposal says what it leaves alone. The absence of a "not in this project" list is not generosity. It means the boundary will be discovered later, usually on an invoice.
• An honest account of your current systems. The spreadsheet, the old database, the vendor you cannot leave yet. If the proposal reads as though you are starting from nothing, the first month will be spent discovering that you are not.

If this part of the proposal is thin, everything after it rests on guesswork, however precise the price looks.

Clear definitions

Does it say what done means?

This is the statement of work, and it is where a proposal earns or loses your trust. The test is simple: could someone who was not in the room read the statement of work and tell, at the end, whether the developer delivered it? If the answer depends on goodwill, it is not a definition.

What a good statement of work contains, piece by piece:

• The change. What will exist that does not exist now, and the concrete outcome. "A booking page your customers use from their phones; double bookings stop." Not "a modern booking solution."
• Constraints. The boundaries. What it must work with (your accounting system, your phone line), what it must never do (email a customer without a person approving it), and who supplies what (you provide the price list by a named date).
• Acceptance criteria. The conditions that mean done, specific enough to test. "A customer can book, change, and cancel without calling you." "The Monday report matches the bank to the penny for three weeks running." Each one is a sentence you can check as true or false.
• Non-goals. What is out of scope, by name. This is the list that protects both of you. It is the difference between "that was never in the project" and an argument.
• Assumptions. What the developer took to be true in order to write the price. If an assumption turns out to be wrong, the price changes, so you want to see them before you sign, not after.

We write every unit of work in the first four of those (change, constraints, acceptance criteria, non-goals), and the fifth is the one we ask a client to read most carefully. A developer who uses different headings is fine. A developer who has no equivalent of acceptance criteria is asking you to decide what done means later, when the leverage has moved.

Watch for the words that cannot be tested: "robust," "modern," "seamless," "best practices," "or equivalent." Each one is a decision that has not been made yet. Ask what it means in your case, and get the answer into the document.

Where this discipline comes from, if you are curious: Meeting in the Middle tells the story of a build where the written requirements were the only place the builders and the testers were allowed to meet, and Put Me In, Coach is about what the person in the middle actually does.

Visible milestones

Does it show you how you will see progress?

A project you cannot see is a project you are financing on trust. Milestones are how a proposal replaces trust with evidence. Each milestone should name three things:

• Something you can see and use at the end of it. Not "database design complete." A screen you can click, a report you can read, an import of your real data you can check. If the first milestone produces nothing you can look at, ask why.
• An acceptance step. A demo on your data, a meeting, and a written note of what was accepted and what was not. We record that review so there is something both sides can read a month later. The format matters less than the fact that it exists and is written down.
• A payment tied to it. Paying by milestone means you pay for something you have seen. Paying by the month means you pay for time. Both are legitimate; know which one you are being offered, and be wary of a large payment before the first visible result.

Read the milestone list as a story. Does the first one reduce your biggest risk, or is it simply the easiest work? Does the order make sense for your business (the booking page before the reporting, if bookings are the problem)? Is there a point where you could stop and still have something useful, if circumstances change? A plan with an early, usable stopping point was written by someone who has watched projects change course.

Two more things to check: who is in the acceptance meeting (you, not only the developer), and what happens when a milestone is not accepted. The answer should be a defined fix round, not a debate about what the definition meant.

Change requests and scope

You will change your mind. That is not a failure; it is what happens when you see the thing for the first time. A proposal should say what happens when you do.

Look for a change process that is short, written, and priced before the work. In practice: you ask, the developer writes the change in the same form as the rest of the work (what changes, what it costs, what it moves), and you approve or decline before anything is built. No work from a hallway conversation.

Three things to be wary of:

• Silent scope. Work that was never in the statement of work appearing in the project, or on an invoice, without a request you approved. Ask how that is prevented.
• Scope that only grows. If the change process has no way for you to take something out, every change is an increase.
• A "we'll figure it out" posture. It sounds collaborative. It means the price is open.

When the project closes, everything in the original definition should be in one of three piles: done, on a follow-up list with a price, or dropped by agreement. Anything in none of them was dropped quietly. A developer who keeps those three piles honest is worth more than one who promises nothing will change.

Warranties and handover

The proposal should say what you own and what happens after the last milestone.

What you own:

• The code, in a repository in your name, or under a written license that says what you can do with it.
• The accounts. Hosting, the domain, email sending, and every third-party service the software depends on, opened in your name, paid by you, with the developer added as a collaborator. A business whose software runs on a developer's personal accounts does not own its software.
• Your data, exportable in a form another developer could use.
• Documentation. Enough that a competent stranger could keep the lights on. Not a manual; a map.

What happens after:

• A defect window. A stated period after each milestone, or after launch, during which fixing a defect is included. "Defect" should be defined by the acceptance criteria (it does not do what the definition says) rather than left to feel.
• Support, priced separately and scoped. Keeping a system running is different work from building it. A proposal that bundles the two forever is hiding one price inside the other.
• Handover, in case you ever need it. What you would be given, in what form, if you moved to another developer. The honest answer is a short list. A developer who cannot give you one is telling you something.

Questions to ask

These are fair to ask any developer, including us. What matters is not only the answer but how quickly and plainly it comes.

1. What did you learn about my business while writing this that I did not tell you?
2. Which part of this are you least sure about, and what would change the price?
3. What is the first thing I will be able to see and use, and when?
4. How will we both know a milestone is done? Show me what acceptance looks like.
5. If I ask for a change in the middle, what exactly happens, and how is it priced?
6. What is deliberately not in this project?
7. Whose name will be on the hosting, the domain, and the other accounts?
8. If we parted ways after the second milestone, what would I be holding?
9. Who does the work, and who checks it against what we wrote down?
10. What does this project need that you have not built before?

A developer who welcomes these questions has been asked them before, usually by their own conscience. A developer who treats them as suspicion is showing you what the review meetings will feel like.

Checklist

Bring this to the meeting. A proposal does not have to satisfy every line, but every blank should start a conversation, not a surprise.

Alignment

• My problem is stated in words I recognize.
• It names something learned in discovery that I did not say.
• It names who will use the software, and when.
• It says what it is not solving.
• It accounts for the systems I already have.

Definitions

• Each piece of work says what changes and what the outcome is.
• Each piece has acceptance criteria I could check as true or false.
• The non-goals are listed by name.
• The assumptions behind the price are written down.
• No "robust," "seamless," or "or equivalent" is left undefined.

Milestones

• Each milestone ends in something I can see and use.
• Each has an acceptance step with a written record.
• Payments are tied to milestones, or the time basis is stated plainly.
• The first milestone reduces my biggest risk.
• There is an early point where I could stop and still have something.

Change, ownership, and after

• Changes are written and priced before work begins.
• Scope can shrink as well as grow.
• Code, accounts, and data are in my name.
• A defect window is defined, and so is "defect."
• Support is priced separately and scoped.
• Handover is described.

Align, define, sign

The three questions in this guide are the three stages we run a project through. Alignment before building is discovery, and it ends when both sides can state the problem the same way. Clear definitions is the statement of work, and it ends when done is written down. Visible milestones is delivery, and it ends when you have accepted the last one. The proposal is the first place you see all three at once, which is why it deserves to be read as more than a price.

Once you sign, the same three questions keep working: is this change aligned with the problem, is it defined, and which milestone does it belong to? Running a project from the buyer's chair is its own guide, and the next one we intend to write. If you are holding a proposal now and would like a second pair of eyes on it, that is a conversation we are glad to have, whoever wrote it.