Specifications are your job
Why producing detailed specifications is the job of engineers, and some ways how to do it.
Engineers often wish for crystal-clear requirements. The reality is that clarity rarely arrives fully formed - it’s something we create together. Because engineers understand the technical landscape more deeply than anyone else on the team, we’re uniquely positioned to turn fuzzy ideas into actionable plans. That’s not a burden; it’s a chance to guide the work toward success.
Navigating ambiguity is part of the craft
Every feature begins as a hopeful sentence: “What if we had Uber for food?” Questions quickly follow: Who are the customers? How will delivery work? What does success look like? Rather than seeing these questions as blockers, we can treat them as invitations to explore.
Tolerance for ambiguity grows with experience. Junior engineers may need support breaking down work. As we progress, we’re expected to bring order to the uncertainty - mapping options, highlighting risks, and collaborating with product and design to define the outcome.
A practical way to build specifications
One approach I love introduces specification writing alongside testing fundamentals. It works best for small features, making it ideal for early-career engineers, but the mindset scales to bigger projects.
- List test cases. Describe each behaviour the feature should support (or prevent) in plain language. Anyone in the organisation should be able to read it and understand what’s expected.
- Break steps into Arrange, Act, Assert. Arrange sets the context, Act performs the behaviour, and Assert confirms the result. This mirrors the structure we use in automated tests and keeps the plan organised.
- Consider modes. Identify the environments or variations that matter - devices, browsers, accessibility settings, locales, data states. Laying them out in columns reveals how the effort multiplies as modes increase.
- Capture results and gaps. As you walk through the plan, record what works, what fails, and what you haven’t tried yet. Share those findings with the team so decisions about scope and risk are informed and transparent.
Here’s a simplified example:
| Step | Action Type | Desktop | Mobile | Dark Mode |
|---|---|---|---|---|
| Uploading a file without an account prompts signup | ||||
| Log out and open the home page | Arrange | |||
| Upload a valid JPG under 100MB | Act | |||
| See the signup dialog | Assert | ✅ | ✅ | ⬜ |
Seeing an empty checkbox instantly highlights a gap. Maybe dark mode isn’t critical for launch, or maybe it is. Either way, the team can decide intentionally because the expectation is explicit.
Why this works
- It surfaces edge cases. While drafting the plan you’ll encounter questions no one has asked yet. Bring those questions back to the team so you can design the right experience together.
- It quantifies risk. Not every scenario must be tested before launch. Documenting what you didn’t test helps stakeholders make informed trade-offs instead of assuming everything was covered.
- It clarifies maintenance cost. Modal features like dark mode or localisation multiply the surface area. Visualising that growth helps teams prioritise wisely.
- It bridges to automation. Once the manual plan exists, you can translate important cases into automated tests. Engineers see firsthand how their intent maps to code, which demystifies testing strategies.
Bringing it back to specifications
A specification is simply a shared list of expectations. A test plan is the same list paired with evidence. When engineers help produce both, we reduce surprises, empower our teammates, and set ourselves up to verify the behaviour later. Instead of waiting for someone else to hand us perfect requirements, we collaborate to create them.
So the next time a project feels under-specified, lean in. Ask questions, outline scenarios, and draft the first version of the spec. Invite product, design, and QA to refine it with you. Your expertise is exactly what turns ambitious ideas into dependable software.