What should a technical brief contain?

A solid technical brief rests on three things: goal, description, and implementation details. Without any one of them, a developer will either guess or fire off a dozen questions before starting. Let's break each one down.

  • Goal — the problem this spec will solve once implemented;
  • Description — a short summary of what exactly is being built or changed;
  • Implementation details — a thorough explanation of how the goal is reached, written in a developer's language: which fields in which records are created or edited, what the interface should look like, and so on. Be unambiguous — after reading, no questions should remain. If a similar solution already exists somewhere — in another industry, another project — reference it as an example. It saves a significant amount of time.

What does "unambiguous, no questions left" actually mean? A real example makes it clearest.

Imagine a client's request: "I want orders from the website to sync with the CRM and trigger a task." Sounds clear enough. But for a developer it's almost meaningless. Here's how the same requirement looks in a proper technical brief (figures and names below are illustrative):

When a customer places an order on www.testsite.com (WordPress site, WooCommerce shop plugin), a Deal + Contact must be created automatically in the CRM in the "Main" pipeline at the "Incoming lead" stage. Immediately upon creation, a task must be assigned to the responsible sales rep: date set to 12.10.2020 (or the deal creation date), due the same day 15 minutes later — i.e. 12.10.2020 at 15:00 — type "Call", task text "Review new lead from website".

Deal name: "New website order #…", where #… is replaced by the internal order number from the site.

Product data — name, quantity, SKU, and unit price — is written into the "Product list" field (type: text area) in the Deal card.

The total order value goes into the "Budget" field of the Deal card.

The address from the "Delivery address" field on the site is written into the "Delivery address" field of the Deal card. This field needs to be created first, type: text area.

In other words, you need to specify:

what, from where, to where, in what format, under what conditions, and at what moment each piece of data must be written, copied, created, or deleted. Six questions — and when each has a clear answer, the brief is done.

One more thing: use the vocabulary of the system you're working with. In Kommo CRM the entities are Contact, Company, Deal, Customer, Task, pipeline, pipeline stage, and fields with specific types (text, dropdown, etc.). There is no "Client" or "Lead" as a standalone concept — using those words in a spec creates confusion about what you actually mean.

Why all this detail? To price the work accurately. Every additional sentence genuinely adds cost. For example, the innocent phrase "I want it to happen 5 minutes after…" means the developer has to write a separate algorithm that counts those 5 minutes from the right moment. A small line in the text is a separate task in the work.

If putting together a spec like this feels difficult on your own, we can help get it into shape. All we need from you: write a draft as close to the example above as you can, put it in a Google Doc, and share it with us at chisla.com.ua@gmail.com with editing access.

We'll read it, leave clarifying questions directly in the document, and once we have your answers we'll bring the spec to a working state. We'll price the finished brief within one or two days and give you the timeline and cost.

We look forward to working with you.