Writing Specifications

Skriva specifikationer / Writing Specifications

Best practices for creating clear, actionable feature specifications.

General Principles / Allmänna principer

Be Specific / Var specifik

Good / Bra

"The user can filter leads by status (New, Contacted, Qualified, Lost)"

Avoid / Undvik

"The user can filter leads"

Focus on the Problem / Fokusera på problemet

Before describing a solution, clearly state the problem:

❌ "Add a button that exports to PDF"
✅ "Customers need to share quotations with their partners who don't have system access"

Use Personas / Använd personas

Reference the defined personas:

• Administrator - Office staff managing leads, quotations, contracts
• Craftsman - Field workers executing projects
• Customer - End clients receiving services

Language / Språk

Write in Your Preferred Language

Both Swedish and English are welcome. The templates support bilingual content with parallel headers:

## Beskrivning / Description
[Your content in Swedish or English]

Use Domain Terms Consistently

Refer to the Glossary for standard translations:

When you mean...	Use...
Price quote	Offert / Quotation
Work item	Arbetspaket / Work Package
Contract	Avtal / Agreement

Structure / Struktur

For New Features

Use the Feature Spec Template:

1. Problem statement
2. Proposed solution
3. User stories by persona
4. Acceptance criteria
5. UI/UX requirements

For Quick Requirements

Use the User Story Template:

• As a [persona]
• I want to [action]
• So that [benefit]

For Existing Feature Changes

Use the Improvement Template:

1. Current behavior
2. Desired behavior
3. Motivation

Acceptance Criteria / Acceptanskriterier

Write testable criteria using Given/When/Then:

**Given** I am viewing a quotation
**When** I click the "Send to Customer" button
**Then** the customer receives an email with a link to the quotation

Priority Guidelines / Prioriteringsriktlinjer

Priority	Swedish	Use when...
Must-have	Kritiskt	Feature is essential for the module to work
Should-have	Viktigt	Feature adds significant value but isn't blocking
Nice-to-have	Önskvärt	Future enhancement, not urgent

Common Mistakes / Vanliga misstag

1. Too vague - Be specific about what, who, and why
2. Solution-focused - State the problem first
3. Missing acceptance criteria - How will we know it's done?
4. Forgetting personas - Who is this for?
5. Scope creep - Keep features focused; split large features

Examples / Exempel

See existing specs in docs/product/specs/ for reference.