What it is
A document stating exactly what we build, what the client receives and how to check it is done. Without it the "I thought that was included" argument is inevitable.
How we use it
We write the specification after a free audit and set timelines once it is approved. The same document becomes the project README on delivery.
Where a specification helps a business
- You are ordering a website, a bot or an automation and want to know in advance what you will get and how to check it.
- Several people work on the project, and each has their own picture of the result.
- A year from now another developer will arrive and need to understand how everything works.
How we use it
- A free audit. We work through the task: who uses it, which actions are needed, where the data comes from, what already exists.
- The specification. We write down what exactly we build, what the client receives and the criteria for checking it is done. For bots, for example, it describes the dialogues and the permissions of each role: what a customer, an employee and an administrator see.
- Timelines after approval. We name them once the specification is agreed, not by eye before it.
- The specification becomes the README. At handover the same document turns into the project README: purpose, features, stack, installation, environment variables, acceptance criteria, known limitations. Next to it sits a CHANGELOG with the version history.
The README's acceptance criteria are what the result is checked against. For the VPN setup guides, for example, there are five: the pages open with no console errors, expand to full screen in Telegram, the bot link leads to Telegram, the layout reads well on a phone, and the steps match the client app's interface.
What happens without one
- "I thought that was included." The client expects one thing, the developer built another, and there is nothing to settle it because nothing was written down.
- Meaningless deadlines. A deadline without a scope is a promise that can be neither kept nor checked.
- Limitations surface in production. What would be honestly listed under "Known limitations" turns up as a customer complaint instead.
When you do not need it
For a small change, such as editing a text or adding a field, a separate specification is overkill: a description in a message is enough. You need one when there is something to check at handover.