So where, exactly, is the spec?
Who should write the requirements, why the document matters, and what to do when there’s no analyst on the team.
A technical specification is the basis for a defined piece of work. It records what needs doing, the requirements and constraints, and the result we expect. A good spec saves communication time, cuts out repeated explanations, confirmations, and conflicting accounts. It helps reveal problems early, separate responsibilities, estimate the work, and make review and acceptance easier.
The client understands what they’re paying for, the team can estimate the task, and the manager doesn’t have to explain the same thing in a different way every time. If the budget is already agreed, the task description helps establish what it actually covers. Otherwise, a project can quietly become an all-you-can-request buffet of revisions.
Written agreements also help in a dispute. Their legal effect depends on how the specification was approved and connected to the contract, though. Having a document doesn’t guarantee anything by itself.
Does the PM have to write the spec?
Not necessarily. Especially if the team has an analyst, architect, or technical specialist responsible for working through requirements. On a complicated project, the manager doesn’t need to impersonate a developer and invent the system architecture alone. But a PM still needs to understand specifications: what to ask the client, which questions to take to specialists, where agreed requirements end, and how the result will be accepted.
For a simple task that doesn’t need a dedicated analyst, a manager can write the spec. For a complex task, organise its preparation with the team and make sure it gets approved. And yes, sometimes you will have to write the damn thing yourself.
What belongs in a specification
- What? The work we’ll do and the elements and features we’ll create.
- Where? Where the elements sit and which part of the product will change.
- When? Agreed deadlines and sequence of work, where relevant.
- How? Expected behaviour, rules, constraints, and dependencies.
- From where, and to where? Data sources, destinations, migrations, and integrations.
- Why? The problem we’re solving and the outcome we expect.
- What else? Permissions, errors, validation, exceptions, and unusual scenarios.
- What will we get? What the result looks like and how we’ll know the task is complete.
- How will we show it? What we’ll demonstrate to the client at handover, and in what format.
Some objects need separate descriptions for creating, displaying, editing, and deleting data. Others need moderation, validation, automatic updates, or archiving. Don’t mechanically add the entire collection to every ticket. Describe what actually applies.
Can we skip the spec?
Let’s not.
More precisely, you can skip an enormous document for every tiny change. Skipping recorded requirements is another matter. Sometimes the client doesn’t want to approve a spec because they haven’t decided what they want. Sometimes it feels like bureaucracy. Occasionally they really do prefer vague requirements because extra work is easier to demand that way.
What matters to us is that undefined requirements leave the team working blind while each side imagines a different result. At least a minimal description is necessary. A few lines in the task tracker may be enough for a simple change. Complex functionality needs proper requirements work with an analyst and technical specialists.
How to set a task clearly
Clarity and simplicity are the main rules. A junior and a senior should both understand the spec. At the same time, it needs enough detail that nobody has to guess the requirements.
Suppose the client needs a banner for a new promotion. Here’s what the task might look like.
NOT LIKE THIS
Hey! Just got back from the stand-up. What have you got?
Hi, the client urgently needs a banner for a new promotion. Something like “Stay home with us” for the text, unless you think of something better. Some greenish colours. Mainly, make it home-themed or something. Can you do it by seven? We need three options.
The task in the tracker
We need a 468 × 60 px banner for the promotion (link). It will appear across the site. Text: “Stay home with us”.
Colours: the brand colour #00B800 must be included. Font: the same as the site’s main headings; bold is fine.
Idea: remote working, somewhere between office and home, but cosy. No photos of people; focus on the surroundings.
References: link 1, link 2, link 3. Still to agree: number of options, final file formats, and delivery timing. Requested deadline: 19:00.
+ A message to the designer
Hey! Just got back from the stand-up. What have you got?
Hi! There’s a fairly urgent task assigned to you. We’re provisionally allowing about half a day. We’ve discussed the requirements with the client; the task is in the tracker. Have a look and see whether that’s realistic. If you have questions or doubts, let’s talk.
In the second example, the person doing the work has specifics. But even here, don’t pretend it’s completely ready to start. Check the timing and number of options with the designer first.
What a poor spec gives away immediately
- Unclear goals and tasks.
- Too little technical detail.
- Vague or missing deadlines.
- Requirements that haven’t been agreed by the parties.
- No owners or approval process.
- No acceptance criteria.
- Missing links to necessary third-party documentation.
- Unchecked service terms, licences, or other restrictions.
- No distinction between included work and additional changes.
Working with requirements
Discovery. Identify requirements, uncover needs, and find the problems the task should solve.
Analysis. Work through the requirements, separate the essentials, and identify contradictions and missing information.
Adaptation. Assess them against the team’s capabilities, budget, existing product, and business processes. For complex work, analyst and technical input is especially important here.
Documentation. Record the agreed requirements and the questions that remain open. Update the document after clarifications, so the team doesn’t work from an obsolete version.
Length, structure, and scope
The more complex the project, the longer the specification may be. Some run to 250–300 pages. Page count isn’t a quality measure, though. For a small task, one to three lines can be enough if they genuinely contain everything needed.
Get used to describing even simple tasks properly. Otherwise, large projects will be painful. Use sections, subsections, tables, or checklists. Structure should make a document easier to navigate, not turn it into a bureaucratic monument. Don’t leave unapproved details to the implementer if they affect the outcome. Equally, don’t describe every button to pad out the document. Match detail to complexity.
Set achievable deadlines. Allow time for document approval, specialist work, checking, and acceptance. Don’t promise dates on the team’s behalf before discussing the scope with them.
Avoid abstract requirements such as “navigation must be convenient”. Convenient for whom? How do we decide it’s done? Describe specific behaviour instead: users can move from a product card to its category, return to search results, or open the basket within an agreed number of actions, if that criterion has actually been agreed.
Define the scope. Undocumented, unapproved functionality shouldn’t automatically become free extra work. But “everything else is up to the implementer” isn’t a universal safety net either. Agree how scope changes and additional approvals will be handled.
A brief for a designer
Design is creative work, so give the specialist answers to most of their questions and clear boundaries from the start. Provide size and format requirements, the client’s site, the agreed idea, references, and the necessary copy. You can’t just hand over wireframes and expect fully designed pages to materialise.
The minimum for website design:
- A completed brief, especially for a redesign.
- Agreed design requirements.
- Examples and references.
- Brand colours, logos, and other client assets.
- Fonts and information about usage rights.
- Approved page wireframes, where the process calls for them.
When making wireframes, avoid filler such as “Lorem ipsum” or “Text text text, pricing goes here”. Prefer real client material, or at least copy close to the final meaning and length. It makes each block’s purpose and design easier to assess for the designer, manager, and client alike.
Understand basic file-format requirements when collecting assets. A JPG isn’t the best source for an icon, and a 100 × 100 px logo is unlikely to work on a large banner. If you need a scalable logo, ask for a vector.
If the designer works in Figma, check which source files they can use. Don’t automatically send a PSD and expect a normal editable document. Before confidently promising a deadline, consult the designer and establish at least a rough time range.
A specification for a developer
To make a feature or page task clear to a developer, include links to the relevant sections, interface examples, screenshots, and detailed explanations. Highlight a specific element on the screenshot instead of making everyone play “find the button”. But pictures alone aren’t enough. Describe what should happen, under which conditions, and what counts as correct.
For a form, specify fields, required inputs, validation, error messages, post-submission behaviour, and where the data goes. If existing functionality is affected, establish what must remain unchanged.
For complex tasks, work through requirements with an analyst and developers. The manager gathers the initial information, coordinates approval, and makes sure questions don’t quietly die somewhere between client and team. If the budget doesn’t cover separate design work, existing styles and components may be suitable. Agree that with the client and record it in advance.
A brief for an SEO specialist
When a client requests SEO work, record the requirements in the work system: what to do, on which pages, why, and what outcome they expect. For a first copywriting task, ask for examples from other sites, not necessarily in the same industry. Find out what they like and what they want in terms of content, structure, and voice.
If they dislike a search snippet, ask which search engine and query they used. Request a screenshot, page link, and an example of the desired result. Clarify whether the specialist should analyse, recommend, propose alternatives, or implement agreed changes.
And don’t promise an exact snippet without checking. Search engines can generate their own, so the SEO specialist doesn’t control every part of the result.
Where that leaves us
A specification doesn’t have to be enormous, and the PM doesn’t have to write it alone. Understanding requirements and setting a clear task are still part of the job.
If there’s an analyst, work with them. If technical expertise is needed, involve the team. If the task is simple, describe it yourself.
The point is that nobody finishes reading and asks, “So what am I actually supposed to do?” And a month later, we don’t discover that the client imagined one thing, the manager agreed another, and the team built a third.
I’m a project manager. About working with russian clients and teams, sharing experience and things I’ve noticed.