Specifications that read: what to write and what to throw away

Open any speculation in Confluence or Notion and honestly answer: did you read it or flip through it to the pictures? And the developer to whom it is addressed? And QA? And the product in three months, when the feature is finished?

Most specifications are written “just in case.” The designer puts everything there: context, research, options, rejected options, justifications, references to Miro, screenshots of the previous version, two paragraphs about the principles. This is a 40-screen document that no one looks at after the first sprint. And then in the chat comes: "Listen, what should be here in an empty state?" - and it turns out that the description was, just no one found it.

The problem is not the discipline of the team. The problem is that a specification is a product that has users, scripts, and a success metric. And if you treat it in the same way that you treat the interface -- you cut it, you take it out, you design navigation -- you start reading it.

## Why is it even important

Specta is not a work report or proof of what the designer thought. It is a tool that saves time for other people. If he doesn’t save, he costs money.

A few things that break down due to bad specks:

• the developer thinks up the behavior and guesses incorrectly - alteration after the demo;
• QA does not understand what is considered a bug and what is a feature, and makes noise;
• the product in a month does not remember why they made this decision, and asks “let’s discuss again”;
• the new person on the team cannot enter the product without a personal tour.

Each of these problems is solved cheaper at the stage of writing the speck than at the stage of release.

## Who Reads Speculation and Why

Before writing, it’s helpful to remember that a document has multiple audiences and needs different ones. If you write “for everyone at once,” you get “for nobody.”.

### Developer

He needs to know what to draw, how each element behaves, what states exist, what data comes in, what to do when errors occur. It doesn’t need the history of the project, the rejected concepts, the philosophy of the partition.

### QA

He needs acceptance criteria in the wording "when - then." What is the correct behavior, what borderline cases to check, what should happen in rare scenarios (no Internet, long text, empty list).

### Products and stakeholders

They need a solution and justification in one or two paragraphs. Not a retelling of the studies, but the conclusion: “chose this option because”. And a link to the details - if you want to dig.

### Future you

After three months, you won’t remember why the button is called that way or why the modular is not a separate screen. One line of “why so” in the game saves an hour of argument.

The conclusion is simple: the document must be arranged in layers. The top is what everyone needs. Deeper is what individual roles need. At the bottom or in the appendices is an archive of context.

## What to throw out of the mix in the first place

The quickest way to improve speculation is not to add, but to remove. It usually turns out that half of the text is not useful to anyone.

Throwing away without regret:

• a retelling of the brief that everyone already has;
• screenshots of the previous version without commenting on what is changing;
• three rejected concepts explaining why they're bad (unless it's a conscious artifact for the archive);
• general reasoning about the user level "our user values convenience";
• links to Miro without specifying what to see;
• layouts of all breakpoints, if the behavior is obvious from one;
• a description of standard components from the design system - a reference is sufficient.

Leave it, even if it seems obvious:

• states: empty, download, error, success, partially filled;
• behavior with non-standard data (very long text, zero elements, 10,000 elements);
• what happens when you cancel, return, update the page;
• access rights: who sees and can;
• depending on other features and flags.

A simple rule for self-checking: if you remove a line from the sinter, someone will ask a question about it in a chat? If not, it can be removed.

## How to make the speck that is read

Then there is the frame, which withstands both the feature on the sprint, and a large section of the product. Not dogma is the starting point from which it is convenient to throw out excess.

### Half-page hat

The top is always the same, in the same order. This is the part that is opened in the chat on the phone.

• one line: what do we do and why;
• status: draft, on review, in work, released;
• links: layout, ticket, past iteration;
• the owner and who reviewed;
• the date of the last significant change.

If a person read the hat and realized whether he should read further, the hat did the job.

### Decision and justification

One paragraph: what you chose and why. No retelling of all options. If there were three options and the choice is not obvious - a short block "why not A and not B", on the line for each.

### Scripts, not screens

The most common mistake is to describe the layout “left to right”. It's impossible to read. It is better to follow user scenarios: “the person comes in for the first time”, “the person returns from the notification”, “the person wants to cancel”.

Inside the script is what sees what he does, what happens in the system, where he goes next.

### Conditions and behaviour

A separate block is everything that does not fit into a linear scenario: empty state, boot, network errors, validation, rights, featureflags. This is the part to which they return most often, so it is convenient to keep it as a checklist, not as prose.

### What's left behind

At the end is a short list of what we are not consciously doing in this iteration and why. This greatly reduces the number of questions "and here you forgot.".

## Workflow: when and what to write

Speka is not written one night before the demo. It grows with design.

### Before the layout - half-page hypothesis

While there is no screen, you can already write: what problem we solve, for whom, how to understand what happened. This is a document to talk to the product, not to develop. The main benefit is to cut off ideas that crumble in words.

### During the layout - a draft with holes

While drawing, the same document is open. There are questions to yourself and the team, found borderline cases, options that were rejected. It's not the final speck - it's a working notebook, and it's normal that half is "???".

### In front of the handover - cleaner

A day or two before the transfer to the development, the draft is rewritten white: everything personal is removed, only scenarios, behavior and states remain. A good sign is if you can cut the volume in half.

### After the release - a short edit

One paragraph: what ended up in the sale, what cut off, what users found. Without this, after six months, no one will understand why the live product differs from the sinter.

## Typical diagnoses

On the review of specks usually the same diseases are repeated. It's good to be able to name them.

Specta diary. A chronological description of how a designer came to a decision. It reads like an essay. It is treated by rewriting from the result, not from the process.

Speca album. Twenty models in a row without signatures. Understanding what is changing and why is impossible. It is treated with annotations and removal of doubles.

Speca-essay. A lot of reasoning about the user and the industry, little specifics. Each paragraph answers a developer or QA question.

Speka-promise. "Here will be described later." After a week is not described, the feature goes into development, the developer writes in chat. It is treated by the fact that the empty blocks are removed - if you do not have time to describe, it is more honest to admit the hole, rather than mask it with a stub.

Speca-copy Figma. Duplicate layout words. If the layout changes, the text becomes obsolete in an hour. Refusing to describe what you can see with your eyes.

## How to apply this in the layout

Speck and layout are one product, not two. A few habits that help a lot.

• On the layout, all non-standard states are signed right next to the screen - not a separate page.
• Components from the design system are not described in words, but marked as instances - you can go to the documentation.
• Abstracts in Figma are short, in the “when – then” format, not in paragraphs.
• Next to the screen are versions of the data: short, long, empty. That’s better than any of the words about “consider the long text.”.
• For complex transitions, a small scheme of states, not three pages of prose.

The more behavior you see right on the canvas, the less there is for the text speck — and the higher the chance that it will be read.

## Questions for self-checking before sending

Before you throw a link into the team channel, it is useful to go through a short list:

• If you read only the hat, you know what the document is about?
• Will the developer find all the states without asking questions in the chat?
• Can QA write test cases without going back to the designer?
• Does the product see the justification of the decision in one paragraph?
• What are we consciously not doing in this iteration?
• Are there any “I’ll describe later” blocks?
• If you remove any section, will anyone notice?

If there is an honest “yes” for each item, the speck is ready. If not, it’s better to spend half an hour now than a week fighting after the release.

## Segment summary

Speck works when arranged in layers, is written in parallel with the layout and undergoes the same hygiene as the interface: cut excess, take the main thing, design navigation. Everything else is implementation details.

## When the basic scheme is lacking

Layer speck and hygiene work for the usual feature in the same team. But there are situations where this is not enough: the feature travels for six months, it is made by three teams, it has a web and mobile, or part of the solution is generated by AI. Here, the spectacle ceases to be a document and becomes an interface between people. And it breaks where any bad interface is at the joints.

### Long feature on a few sprints

If a work is broken down into four or five iterations, one piece for all turns into a cemetery. The working technique is to keep one top-level page with a description of the final state and links to iteration specks. The upper level answers the question “where are we going”, iterative – “what is Katim now”. Without the top level through two sprints, the team forgets the original goal and starts optimizing locally.

### Several platforms

The Web, iOS, and Android are tempted to write three specks. In practice, it is better to have one speck of logic and behavior plus short applications on platform differences. If the differences are more than common, it’s a signal that the product is conceptually divergent, and the problem isn’t the documentation.

### Multiple teams

When the feature is divided between back, front and mobile, the spectacle must clearly say who is responsible for what and where the border passes. It is useful to keep the "contract" section: what events, what states from the server, what errors. Everything else is the details inside the team.

## Speck and AI: What Changes in the Process

AI added two new modes to the work: an assistant that helps write the speculator itself, and a feature whose behavior cannot be described harshly because it is invented by a model. They're different stories.

### AI as co-author of speck

The model rewrites the draft well into the cleaner, pulls hidden states from the description of the flow, generates variants of errors and empty data. Work cycle: the designer throws raw notes and layout, asks to structure according to scenarios, then cleans with his hands.

Where AI lies consistently:

• Invents states that are not in the product and describes them confidently.
• Fills the "describe later" with plausible water, which is difficult to distinguish from real logic.
• Smooth the contradictions in the source instead of highlighting them.

So the draft passage - yes, the final clean cleaner without proofreading - no. The team's review will be awkward.

### Speck for AI feature

If there is a generation in the product, a search with a model, an assistant - to describe "pushed - saw" is useless. Speck shifts to other questions: what prompt and context go into the model, what is considered a valid answer, what is shown at low confidence, how we behave when the model fails, what is logged for markup.

A good sign is if there is a section in the speck “what do we do when the model is wrong?” Bad - if the behavior is described only for a happy occasion, and the mistakes are left "at the discretion of the back.".

### MCP, plugins and auto generation from Figma

Tools that pull data from the layout and collect a draft of the sinter save an hour or two. The risk is the same as that of any auto generation: the document looks ready, and it is no longer read with your eyes. A useful rule is that auto generation gives a skeleton, the meaning is written by a person. If after the plugin, no one edited the text, you can see it immediately on the review.

## How to defend a decision in front of a team

Spectacle is not just read by the developer. It opens on a review with a product, on a synca with another team, on a demo for stakeholders. They are different readers and each has a question.

• Product: Why do we measure what we cut.
• Developer: what states, what extreme cases, what gives the server.
• QA: where are the validation boundaries, which scenarios are required.
• Design Review: How it fits into the system, what new has emerged in patterns.

If there is a short answer to each of these questions, there is almost no need to defend the solution - the document does it itself. If you have to talk a lot in your voice, usually the problem is not with the team, but that the speck does not cover what the designer has in his head.

## Questions for an outside audit

A useful technique is to give a speculator to a person who is not in context before meeting and ask:

• What problem do we solve without my explanation?
• Can you see what we deliberately left behind?
• Where in the document would you ask the question - and why?
• If you were doing this, what is missing?
• What paragraph would you delete without losing meaning?

The answers to these five questions usually give more than an hour of team discussion.

## Segment summary

The more complex the context – a long feature, several commands, AI within the product – the more important it is that the spectacle is not a warehouse of thoughts, but an interface between people. AI speeds up the draft, but does not cancel the proofreading. And the best quality test is not your checklist, but five minutes with a person not from the project.

## Preparedness checklist

Before you send a document to the team, it makes sense to run it on a short list. Not as a formality, but as a way to catch those three or four flops that will then pop up in a developer chat room at an uncomfortable moment.

• In the first screen you can see what problem we solve and for whom.
• There's a clear list of "out of bounds" - which we don't consciously do.
• All states are listed: empty, download, error, partial data, offline.
• The backing contract is described: events, answers, error codes.
• You can see where the validation is on the client, where on the server, and what we show when you fail.
• For each error, it is clear what the user sees and what he can do.
• There is a section about accessibility at least at the level of focus, contrast and voiceover states.
• For AI features, behavior at low confidence and model failure is described.
• Texts are not "Lorem", but real lines agreed with the editor.
• There are no “final-2-ok” layers in the layouts that the speck refers to.
• Anyone on the team finds the right section in ten seconds.

If at least half of the points do not pass, the document is not ready for review – it is ready for you to sit with it again.

## Anti-patterns that occur more often than others

### Speck-album

Twenty screens in a row, between them empty comments "here everything is clear." It is impossible to read: it is not clear where the flow begins, where the alternative branches are, where the options are just to think. Treatable by splitting into scenarios and explicitly marking "main stream/alternatives/discarded.".

### Protocol of the meeting

Document with the history of decisions: “discussed with Petya, agreed so, then changed their minds.” Useful for the archive, useless for the artist. Make decisions in a separate log, leave only the result in the sin.

### Spek-wiki

Everything in one infinite file: product goals, research, competitors, layouts, texts, analytics. It is scary to open, it is impossible to search. A short document hub with links is better than a monolith.

### Spek diagonally

When the author wrote to quickly close the drag, not to read it. Signs: the same wording in all states, copypast between screens, errors in field names. On the review, the developer asks three questions for each paragraph.

### One-man steak

It is written so that only the developer with whom the author discussed the feature in voice understands it. The new man in the project gets lost. The test is simple: give speculation to a colleague on the next team.

### Speck, who is afraid of solutions

Everywhere “probably”, “probably”, “to discuss”. The document shifts the choice to the reader, and each does in his own way. If the solution is really open, it should be explicitly marked as an open question with the owner, not dissolved in the text.

## Questions to ask yourself before sending

• What would I take away from this document if I was given five minutes?
• What are the three most important paragraphs and are they at the beginning?
• What I didn’t write because “it’s clear” – and who understands it?
• If they do it without me, what will break first?
• What states did I come up with on the go while I was writing and not drawing in the layout?
• Where in the document do I cover with words what I did not solve in design?

The last question is the most unpleasant and most useful. Speck often becomes a place where the designer hides the ill-conceived: “process correctly”, “show a suitable message”, “behave as expected”. Each such place is a future bug or a future dispute.

## Practical outcome

Good speck is not volume and not beautiful design. This is a document from which a person who did not sit with you in meetings can assemble a product without guessing. Three habits are enough to make it so: write with scripts and states, not screens; explicitly say boundaries and contracts; and ask yourself each time which pieces can be removed without losing meaning. Anything that survives these three filters is usually the part of the sinter that is actually read.