A technical specification is a document everyone wants to have and nobody wants to write. The client thinks the contractor should write it, since he is the specialist. The contractor thinks the client should provide it, since it is his business. In the end the spec is written in a hurry, at the last moment, as two pages of general words, and the project starts on a foundation of sand.
I have seen bad specs kill projects that could have become wonderful. And I have seen good specs save projects with a mediocre team. This is no exaggeration: a specification is a contract between business and development. The clearer it is, the fewer conflicts at acceptance, the more accurate the estimate and the less money goes into rework.
A blueprint, not a wish
No architect will start building a house from the words "I want it nice and comfortable". He will ask: how many floors, how many people will live there, is a garage needed, what is the budget, what is the plot, where does the sun rise. Then he will draw a blueprint showing every wall and every window. And only after the client signs that blueprint will the builders get to work.
In software development, for some reason, people believe you can do without a blueprint. "Let's start and figure it out along the way." That works right up to the first argument, which sounds like this: "But I told you I needed...", and the reply: "No, you didn't." Both are right, because each remembers his own version of the conversation. A spec exists precisely so that there is only one version.
What a spec must contain
Goals and business logic. Why the system is being built, what problem it solves, who will use it. This is the first section and the most important. If a developer does not understand the goal, he will make decisions blindly. When the goal is clear, the team itself suggests simpler and cheaper ways to reach it.
User roles. Who works with the system and what each is allowed to do. Client, manager, administrator, accountant: each has his own set of screens and actions. Half of the architecture is born from this section.
Detailed description of functionality. Not "the system should manage orders", but concrete scenarios: the client places an order, chooses delivery, pays, gets a notification; the manager sees the order in the list, changes its status, contacts the client. Each scenario with a start, steps, branches and a result.
Data structure. What entities exist in the system and how they are related. Client, order, product, payment. This is the language that both the business and the code will speak. If the names in the spec and in the program do not match, in a year nobody will understand what is what.
Design requirements. At least screen sketches, even hand-drawn. One interface sketch removes a dozen questions.
Non-functional requirements. Speed, security, number of users, backups, supported browsers and devices. These are forgotten most often, and they are exactly what later become the most expensive surprises. I wrote a separate article about them and strongly recommend going back to it.
Acceptance criteria. How we will know the system is ready. Concrete, verifiable conditions, not "everything works well".
Rules I have learned from practice
First: write for someone who was not at your meetings. The spec will be read by a new programmer six months from now, a tester who joined mid-project, another contractor if things do not work out with the first. Everything that is "obvious anyway" is obvious only to you.
Second: one requirement, one thought. The requirement "the system must be fast, convenient and secure" cannot be verified. Split it into three, and for each write down what exactly fast, convenient and secure mean.
Third: describe what to do when things go wrong. Most specs describe only the happy path: the user entered everything correctly, the payment went through, the server responded. Reality consists of errors, cancellations, empty fields and connection failures. Bugs and arguments are born exactly at those forks.
Fourth: a spec is a living document, but with rules for change. Requirements will change, that is normal. But every change must be recorded, estimated and approved, not just tossed into a chat. Otherwise in a month the spec no longer reflects reality, and everyone is back to working from memory.
Fifth: do not try to describe everything at once. The first version of a product needs a spec for the first version. A detailed description of features that will appear in two years is wasted time, because by then everything will have changed.
Who should write the spec
My answer: together. The client knows his business but not how to turn it into a program. The contractor knows how to build programs but not the client's business. A good spec is born in a dialogue where a business analyst or architect asks questions, the client answers, and both sides draw and correct the same picture.
If a contractor takes on a project without a spec, or with a two-paragraph one, and immediately names a fixed price, be careful. Either he built in a huge buffer, or you will soon learn that "this was not part of the agreement".
How we do it at Ingello
We went further than the classic text spec. At Ingello Systems part of the specification is written not in prose but in formal descriptions: a data schema in SFL, a map of screens and scenarios in ISFL, interface markup in IFL. The Fractal generator turns that description into a working prototype with a database, API and admin panel. The client sees not a fifty-page document but a system he can click through within a few days. And arguing becomes much easier: here is the screen, here is the data, is this what you wanted or not?
But even without generators the principle is the same: the closer a spec is to a blueprint and the further from a wish, the more successful the project. If you start a new project tomorrow, begin not by looking for developers but by answering the question an architect would ask: what exactly are we building, for whom, and how will we know we have built it.
