Software Engineering

The Traceability Chain

A useful mental model for how engineering documentation fits together:

Business Need
    ↓
Requirements (what)
    ↓
Acceptance Criteria (how to verify what)
    ↓
Design (how to build it)
    ↓
Implementation
    ↓
Tests (based on acceptance criteria)

Key Principles

1. Traceability is Key

Every requirement should link to:

• a design element
• one or more acceptance criteria
• one or more tests

2. Avoid Mixing Levels

Common mistakes:

Læs videre

Design Documents

Design documents describe how requirements will be implemented. They bridge requirements → implementation → verification.

What They Are For

• Translate requirements into system structure
• Align developers and engineers before implementation
• Define interfaces, data flows, and responsibilities
• Reduce ambiguity in complex systems
• Provide traceability back to requirements

Typical Structure

1. Overview — purpose, scope, assumptions, constraints
2. Requirements reference — links to relevant requirements (traceability matrix optional)
3. High-level architecture — components, responsibilities, data flow
4. Detailed design — data structures, state machines, algorithms, interface definitions
5. Edge cases and failure handling — recovery strategies, validation rules
6. Non-functional considerations — performance, security, maintainability, scalability
7. Open questions / decisions — design trade-offs, alternatives considered

What a Design Document is NOT

• Not a requirements document
• Not a step-by-step implementation script
• Not code (though diagrams and pseudocode are fine)

Se også: Requirements Engineering, Pharma Automation Framework

Læs videre

Acceptance Criteria

Acceptance criteria define how you prove a requirement is satisfied. They are concrete, verifiable, written in behavior terms, and often expressed as scenarios or rules.

Common Formats

Rule-based

Given X, system shall do Y.

Scenario-based (Given / When / Then)

Given a valid batch recipe, When the user starts execution, Then the system shall validate parameters before proceeding.

Key Properties

• Binary outcome — pass or fail, no ambiguity
• Focus on observable behavior — not implementation details
• Directly usable for testing — a tester can derive test cases

Relationship to Requirements

Think of acceptance criteria as the test contract for a requirement. Every requirement should link to one or more criteria.

Læs videre

Requirements Engineering

Requirements describe what the system must achieve, not how. They sit at different levels of abstraction.

Levels of Requirements

1. Business Requirements

The highest-level intent. Expresses why something is needed. Usually stable over time.

“The system shall reduce manual batch configuration errors.”

2. User / Functional Requirements

Describes system behavior from a user or process point of view. Focuses on what the system does.

“The system shall validate all recipe parameters before execution.”

Læs videre