Software-Design-Dokument: Vorlage + Beispiel (2026)

Ein Software-Design-Dokument (SDD) ist ein schriftlicher Plan dafür, wie ein System oder Feature gebaut wird, bevor jemand Code schreibt. Es deckt das Problem, Ziele und Nicht-Ziele, den Ist-Zustand, das vorgeschlagene Design, erwogene Alternativen, Risiken und den Rollout ab. So fangen Reviewer teure Fehler ab, solange Änderungen noch billig sind.

Ein vollständiges Design Doc hat 10 Abschnitte:

• Kopfbereich: Titel, Autor, Reviewer, Status, Datumsangaben und Links.
• Kontext und Problem: Was kaputt ist oder fehlt und warum gerade jetzt.
• Ziele und Nicht-Ziele: Wie Erfolg aussieht und was nicht dazugehört.
• Ist-Zustand: Wie es heute funktioniert, mit Screenshots, Metriken und Logs.
• Vorgeschlagenes Design: Architektur, Datenmodell, APIs und UI-Änderungen.
• Erwogene Alternativen: Die anderen Optionen und warum sie verloren haben.
• Sicherheit, Datenschutz, Performance und Observability: Die Prüfungen, die jede Änderung braucht.
• Teststrategie: Wie du beweist, dass es funktioniert.
• Rollout, Migration und Rollback: Wie es ausgeliefert wird und wie es wieder zurückgenommen wird.
• Risiken, offene Fragen und Entscheidungslog: Was noch unklar ist und wer sich darum kümmert.

Unten bekommst du eine Markdown-Vorlage zum Kopieren, ein ausgefülltes Beispiel für ein realistisches Feature und eine Review-Checkliste. Das Beispiel setzt stark auf annotierte Screenshots. Ein Reviewer, der den Ist-Zustand in fünf Sekunden erfasst, diskutiert über das Design und nicht über die Fakten.

Was ist ein Software-Design-Dokument?

Ein Software-Design-Dokument beschreibt, wie du etwas bauen willst und warum du dich für diesen Plan entschieden hast. Geschrieben wird es von der Person aus Engineering oder Architektur, die die Umsetzung leiten wird. Lesen werden es die Reviewer, das Produktmanagement, QA, SRE und alle, die den Code später pflegen.

Es steht zwischen dem Problem und dem Code. Das Problem taucht oft als Stapel von Tickets oder Bug Reports auf. Das Design Doc macht aus diesem Stapel einen gemeinsam abgestimmten Plan, bevor irgendwer einen Pull Request öffnet.

Teams nutzen mehrere Namen für dasselbe: SDD, Design Doc, technisches Design-Dokument (TDD) und Tech Spec. Der formale Vorfahre ist die „Software Design Description“ aus IEEE 1016. Die Ausgabe von 2009 ist inzwischen als inaktiv markiert, und du begegnest ihr vor allem in regulierten Branchen oder bei Auftragsarbeiten. Die meisten Produktteams folgen dem leichteren Stil aus Design Docs at Google: Kontext, Ziele und Nicht-Ziele, das Design, Alternativen und übergreifende Themen.

Wenn du lieber einen kurzen Überblick hörst: Dieses vierminütige Erklärvideo auf Englisch deckt dieselben Punkte ab.

Software-Design-Dokument vs. technisches Design-Dokument, Tech Spec, SRS, PRD, ADR und RFC

Diese Begriffe überschneiden sich, und Teams gehen locker mit ihnen um. Die Tabelle zeigt, wie sie sich meistens unterscheiden.

Kurz gesagt: Das PRD sagt, was und warum, das SDD sagt, wie, und ein ADR hält eine einzelne Entscheidung fest, nachdem sie gefallen ist. ADRs kannst du mit der Vorlage für Entscheidungsprotokolle aus dem Leitfaden zu interner Dokumentation schreiben und jedes davon auf das Design Doc zurückverlinken, aus dem es entstanden ist. Auf der ADR-Community-Website findest du weitere Formate.

Wann du ein Design Doc brauchst (und wann nicht)

Schreib ein Design Doc, wenn eine falsche Entscheidung teuer wäre. Gute Auslöser:

• Die Arbeit dauert länger als etwa eine Personenwoche.
• Sie hängt von einem anderen Team, Service oder Anbieter ab.
• Sie ändert Daten oder eine öffentliche API auf eine Art, die schwer rückgängig zu machen ist.
• Sie berührt Sicherheit, Datenschutz, Abrechnung oder Compliance.
• Die Meinungen zum Ansatz gehen auseinander, oder niemand hat das Problem bisher aufgeschrieben.

Für kleine Änderungen, die du rückgängig machen kannst, lass es weg. Da reicht eine klare Pull-Request-Beschreibung oder ein einzelnes ADR. Wer für einen Fix von einem Tag ein langes Dokument schreibt, bringt dem Team bei, Dokus nur zu überfliegen.

Das Dokument kann auch mit der Arbeit wachsen. Der Google-Artikel oben beschreibt „Mini Design Docs“ mit 1 bis 3 Seiten für kleine Änderungen und längere Dokumente für große Projekte.

So schreibst du ein Software-Design-Dokument in 7 Schritten

1. Sprich zuerst mit den Stakeholdern. Nimm dir je 15 Minuten mit dem Produktmanagement, den Ownern jeder Abhängigkeit, SRE und Security. Frag, was sie dazu bringen würde, Nein zu sagen. Ihre Antworten werden zu deinen Zielen, Nicht-Zielen und Grenzen.
2. Schreib Problem und Ziele vor dem Design. Entwirf Kontext, Ziele und Nicht-Ziele und teil nur diese Seite mit zwei oder drei Reviewern. Einigkeit an dieser Stelle verhindert die schlimmste Art von Nacharbeit: eine gute Lösung für das falsche Problem.
3. Halte den Ist-Zustand mit Belegen fest. Mach einen Screenshot vom kaputten Ablauf, schnapp dir das Dashboard-Panel, füg den Fehlertext ein und verlinke die Tickets. Nummeriere jedes Problem und setz dieselben Nummern auf die Screenshots.
4. Entwirf das Design und mindestens zwei Alternativen. Fang mit einem Diagramm an, dann folgen Datenmodell, APIs und UI-Änderungen. Schreib zu jeder Alternative einen ehrlichen Satz, warum sie verloren hat.
5. Starte ein asynchrones Review. Teil das Dokument mit einer Kommentarfrist von zwei oder drei Arbeitstagen. Wen du einladen solltest, steht unter So bringst du dein Design Doc durchs Review.
6. Setz ein kurzes Review-Meeting an. Nutz es nur für Threads, die sich in Kommentaren nicht klären ließen.
7. Aktualisiere den Status und halte das Dokument lebendig. Markiere es als Freigegeben und später als Umgesetzt oder Ersetzt. Der Abschnitt zur Zeit nach dem Launch zeigt, was du ändern solltest.

Was hineingehört: die 10 Abschnitte eines Design Docs

Jeder Abschnitt beantwortet eine Frage, die ein Reviewer sowieso stellen wird. Lass einen Abschnitt nur weg, wenn du in einer Zeile begründen kannst, warum.

Die Nummern in der Abbildung zeigen auf die Abschnitte, die im Review am meisten Gewicht haben.

1. Kopfbereich: Titel, Autor, Reviewer, Status, Datumsangaben, Links

Gib dem Projekt einen kurzen Namen, den man laut aussprechen kann. Nenn den Autor, die Pflicht-Reviewer und die Datumsangaben und verlinke Ticket, PRD und verwandte Dokumente. Nutz ein einziges Statusfeld mit festen Werten: Entwurf, Im Review, Freigegeben, Umgesetzt oder Ersetzt.

Häufiger Fehler: kein Status, sodass niemand weiß, ob das Dokument ein Vorschlag ist oder festhält, was ausgeliefert wurde.

2. Kontext und Problemstellung

Erklär, was kaputt ist oder fehlt, wen es trifft und warum es jetzt wichtig ist. Schreib für jemanden, der jedes Meeting verpasst hat. Zwei bis vier Sätze plus Links zu Belegen reichen meistens.

Häufiger Fehler: hier schon die Lösung beschreiben. Der Kontext soll beim Leser den Wunsch nach einem Fix wecken, bevor du einen zeigst.

3. Ziele und Nicht-Ziele

Ziele beschreiben überprüfbare Ergebnisse, etwa „Exporte mit 1 Mio. Zeilen sind in unter 3 Minuten fertig“. Nicht-Ziele listen Dinge auf, die ein Leser für Teil des Projekts halten könnte, die es aber nicht sind. Sie verhindern mehr Streit im Review als jeder andere Abschnitt.

Häufiger Fehler: Ziele als Aufgaben („eine Queue einbauen“) statt als Ergebnisse.

4. Ist-Zustand mit Belegen

Zeig, wie das System heute funktioniert und wo es scheitert. Hier verdienen sich Screenshots ihren Platz: der kaputte Bildschirm, das Latenz-Panel, der Fehlerdialog und die Zahl der Tickets. Nummeriere die Probleme in einer Liste und setz dieselben Nummern auf die Screenshots.

Häufiger Fehler: „Exporte sind langsam“ schreiben, ohne Screenshot, ohne Metrik und ohne Ticket-Link.

5. Vorgeschlagenes Design

Fang mit einem Architekturdiagramm an und behandle dann Datenmodell, APIs oder Schnittstellen und UI-Änderungen. Erklär die Abwägungen, die du getroffen hast, nicht jede Codezeile. Wenn sich eine Entscheidung später leicht umkehren lässt, lass sie weg.

Häufiger Fehler: ein Diagramm ohne Link zur Quelldatei, sodass niemand es aktualisieren kann.

6. Erwogene Alternativen

Liste die echten Optionen auf, die du verworfen hast, auch „nichts tun“, mit ein oder zwei Sätzen dazu, warum jede verloren hat. Reviewer vertrauen einem Design mehr, wenn sie sehen, dass der Autor ihre Lieblingsidee schon abgewogen hat.

Häufiger Fehler: Strohmann-Optionen, die niemand wählen würde.

7. Sicherheit, Datenschutz, Performance und Observability

Sag, welche Daten die Änderung berührt, wer darauf zugreifen kann und wie lange sie aufbewahrt werden. Nenn die erwartete Last, die Limits und die Metriken, Logs und Alerts, an denen du erkennst, dass es funktioniert.

Häufiger Fehler: „keine Auswirkungen auf die Sicherheit“ ohne Begründung.

8. Teststrategie

Beschreib Unit-, Integrations-, Last- und manuelle Tests sowie die Testdaten, die du brauchst. Nenn, wer die Abnahme erteilt. QA-Engineers lesen diesen Abschnitt zuerst, also mach ihn konkret.

Häufiger Fehler: „Wir schreiben Tests“ ohne Plan für die schwierigen Fälle.

9. Rollout, Migration und Rollback

Erklär, wie die Änderung ausgeliefert wird (Feature Flag, Stufen, Prozentsätze), wie Daten umziehen und welche Schritte genau zum Rollback gehören. Nenn das Signal, das einen Rollback auslöst.

Häufiger Fehler: ein Rollback-Plan, der nur funktioniert, bevor die Migration gelaufen ist.

10. Risiken, offene Fragen und Entscheidungslog

Erfasse jedes Risiko und jede offene Frage mit Owner und Fälligkeitsdatum. Führ ein datiertes Entscheidungslog, während Threads geschlossen werden, damit spätere Leser sehen, was sich geändert hat und warum.

Häufiger Fehler: offene Fragen ohne Owner, die für immer offen bleiben.

Vorlage für ein Software-Design-Dokument (Markdown zum Kopieren)

Kopier diesen Block in eine neue Datei. Ersetze oder lösche jeden Platzhalter in eckigen Klammern.

# Design Doc: [Projektname]

| Feld | Wert |
|---|---|
| Autor | [Name] |
| Reviewer | [ein Owner pro Abhängigkeit, dazu SRE, Security, QA] |
| Status | Entwurf / Im Review / Freigegeben / Umgesetzt / Ersetzt |
| Erstellt | JJJJ-MM-TT |
| Zuletzt aktualisiert | JJJJ-MM-TT |
| Links | [Ticket], [PRD], [Dashboards], [verwandte Design Docs] |

## 1. Kontext und Problemstellung
[Was kaputt ist oder fehlt, wen es betrifft und warum jetzt. 2 bis 4 Sätze. Verlinke die Belege.]

## 2. Ziele
- [Ein überprüfbares Ergebnis, z. B. „Exporte mit 1 Mio. Zeilen sind in unter 3 Minuten fertig“]

## 3. Nicht-Ziele
- [Etwas, das ein Leser für Teil des Projekts halten könnte, und warum es das nicht ist]

## 4. Ist-Zustand
[Wie es heute funktioniert. Füge annotierte Screenshots, Dashboard-Panels und Log-Auszüge hinzu.]

Probleme (die Nummern passen zu den Markierungen auf den Screenshots):
1. [Problem 1]
2. [Problem 2]

## 5. Vorgeschlagenes Design
### 5.1 Architektur
[Diagramm plus Link zur Quelldatei: Mermaid, draw.io oder Excalidraw.]

### 5.2 Datenmodell
[Neue Tabellen, Felder, Indizes und Aufbewahrungsfristen.]

### 5.3 APIs und Schnittstellen
[Endpunkte oder Events, Request- und Response-Formate, Fehlercodes, Limits.]

### 5.4 UI-Änderungen
[Screenshots oder Mockups von Ist und Soll, mit hervorgehobenen Änderungen.]

## 6. Erwogene Alternativen
| Option | Vorteile | Nachteile | Warum nicht gewählt |
|---|---|---|---|
| Nichts tun | | | |
| [Option A] | | | |
| [Option B] | | | |

## 7. Sicherheit, Datenschutz, Performance und Observability
- Sicherheit: [Authentifizierung, Autorisierung, Secrets, Missbrauchsfälle]
- Datenschutz: [betroffene personenbezogene Daten, Aufbewahrung, Löschung]
- Performance: [erwartete Last, Limits, SLOs]
- Observability: [Metriken, Logs, Alerts, Dashboards]

## 8. Teststrategie
[Unit-, Integrations-, Last- und manuelle Tests. Testdaten. Wer die Abnahme erteilt.]

## 9. Rollout, Migration und Rollback
- Rollout: [Feature Flag, Stufen, Prozentsätze, Termine]
- Migration: [Backfill, Dual Writes, Datenumzüge]
- Rollback: [genaue Schritte und das Signal, das sie auslöst]

## 10. Risiken, offene Fragen und Entscheidungslog
| # | Risiko oder offene Frage | Owner | Fällig | Status |
|---|---|---|---|---|
| 1 | [Risiko oder Frage] | [Name] | JJJJ-MM-TT | Offen |

Entscheidungslog:
- JJJJ-MM-TT: [Entscheidung] ([wer], [Link zum Thread])

Wo die Vorlage liegen kann:

• Im Repo: Speicher sie als docs/design/2026-10-feature-name.md, damit das Dokument in einem Pull Request reviewt und zusammen mit dem Code versioniert wird.
• Google Docs: Aktiviere Markdown unter Tools > Einstellungen, klick dann mit der rechten Maustaste und wähle Aus Markdown einfügen (Google Docs-Editoren-Hilfe).
• Confluence oder Notion: Füg sie in eine neue Seite ein und prüf dann, ob Überschriften und Tabellen richtig übernommen wurden.
• Als PDF: Für Stakeholder, die nur PDFs lesen, wandelst du das Markdown mit dem kostenlosen Markdown-zu-PDF-Tool um.

Von den Machern dieser Seite

Genug von langweiligen Screenshots? Probier ScreenSnap Pro.

Schöne Hintergründe, professionelle Anmerkungen, GIF-Aufnahme und sofortiges Teilen in der Cloud, alles in einer App. Einmal 34 $ zahlen, für immer besitzen.

Preis und Funktionen ansehen

Beispiel eines Software-Design-Dokuments: asynchrone CSV-Exporte

Hier ist ein gekürztes, ausgefülltes Design Doc für ein typisches Feature. Alle Namen, Zahlen und Daten sind Demowerte.

Kopfbereich und Problem

Design Doc: Asynchrone CSV-Exporte im Admin-Bereich. Autorin: Jane Doe. Reviewer: Billing-Owner, SRE mit Rufbereitschaft, Security, QA-Lead. Status: Im Review, Kommentare bis 9. Oktober.

Problem: Die Customers-Seite baut ihren CSV-Export innerhalb eines einzigen Web-Requests. Ab etwa 50.000 Zeilen läuft der Request in den 30-Sekunden-Timeout des Gateways, und Admins sehen einen 504-Fehler. Der Support hat dazu im dritten Quartal 14 Tickets erfasst, und Admins versuchen es erneut, wodurch dieselbe schwere Abfrage noch einmal läuft.

Ziele und Nicht-Ziele

• Ziel: Exporte mit bis zu 1 Mio. Zeilen laufen durch, mit einem p95 unter 3 Minuten.
• Ziel: Admins können die Seite verlassen und bekommen eine Benachrichtigung, wenn die Datei bereit ist.
• Ziel: eine Export-Historie, die Dateien 7 Tage lang aufbewahrt.
• Nicht-Ziele: XLSX-Ausgabe, geplante oder wiederkehrende Exporte und Änderungen daran, welche Spalten exportiert werden.

Ist-Zustand

Der Screenshot unten zeigt drei Probleme, nummeriert passend zu dieser Liste:

1. Der Export-Button blockiert mit einem Spinner und zeigt keinen Fortschritt.
2. Nach 30 Sekunden liefert das Gateway einen 504, und der Toast meldet, dass der Export fehlgeschlagen ist.
3. Die fehlschlagende Auswahl umfasst 84.212 Zeilen, deutlich über der Schwelle von 50.000.

Das Dashboard zeigt, dass es kein Einzelfall ist. Der p95 der Export-Route erreicht bei großen Auswahlen 41 Sekunden, die Datenbank arbeitet also weiter, nachdem das Gateway längst aufgegeben hat.

Vorgeschlagenes Design

Die API baut die Datei nicht mehr innerhalb des Requests. Sie legt einen Export-Job an und antwortet sofort. Die Nummern passen zum Diagramm:

1. POST /exports legt eine Zeile in export_jobs an und gibt 202 mit der Job-ID zurück.
2. Die API stellt den Job in eine Queue.
3. Ein Worker liest die Kundentabelle aus der Read Replica, 5.000 Zeilen pro Batch.
4. Der Worker schreibt eine gzip-komprimierte CSV in den Object Storage. Eine Lifecycle-Regel löscht Dateien nach 7 Tagen.
5. Wenn der Job fertig ist, schickt der Benachrichtigungsdienst eine Benachrichtigung in der App und eine E-Mail.
6. Der Admin ruft die Datei über eine signierte URL ab, die nach 24 Stunden abläuft.

Leg das Diagramm als Code neben dem Dokument ab, damit alle es bearbeiten können. GitHub rendert Mermaid-Blöcke in Markdown-Dateien, Issues und Pull Requests, wie die GitHub-Doku zum Erstellen von Diagrammen erklärt:

flowchart LR
  UI[Admin-UI] -->|1: POST /exports| API[API-Service]
  API -->|2: in Queue einreihen| Q[Job-Queue]
  Q -->|abholen| W[Export-Worker]
  W -->|3: 5.000 Zeilen pro Batch lesen| DB[(Read Replica)]
  W -->|4: .csv.gz schreiben| S3[(Object Storage)]
  W -->|5: Job fertig| N[Benachrichtigungsdienst]
  N -->|Admin benachrichtigen| UI
  UI -.->|6: signierte URL, 24 h| S3

Erwogene Alternativen

Risiken und Rollout

• Datenschutzrisiko: Die CSV enthält Namen und E-Mail-Adressen von Kunden. Dateien werden nach 7 Tagen gelöscht, Links laufen nach 24 Stunden ab, nur Admins mit Export-Berechtigung können einen Job starten, und jeder Download wird protokolliert.
• Lastrisiko: Die Batch-Lesezugriffe könnten die Replica zurückfallen lassen. Gegenmaßnahme: höchstens 2 laufende Jobs pro Mandant plus ein Alert für Replica Lag.
• Rollout: Auslieferung hinter dem Feature Flag async_exports. Zuerst kommen interne Mandanten, dann 10 %, 50 % und 100 % über zwei Wochen. Der alte Pfad bleibt für Exporte unter 10.000 Zeilen bestehen, bis das Flag zwei Wochen lang auf 100 % stand.
• Rollback: Flag ausschalten. Jobs in der Queue laufen zu Ende, und es gibt keine Datenmigration, die rückgängig gemacht werden muss.
• Offene Frage: Brauchen Admins XLSX? Owner: PM, fällig vor dem allgemeinen Release.

Mehr Beispiele aus der Praxis findest du auf designdocs.dev, wo veröffentlichte Design Docs von Engineering-Teams gesammelt werden.

So nutzt du Screenshots und Visuals in einem Design Doc

Diagramme zeigen Struktur. Screenshots belegen den Ist-Zustand und zeigen UI-Änderungen. Ein gutes Design Doc braucht beides, jedes an seinem Platz.

Diagramme für die Struktur, Screenshots als Beleg

Zeichne Architektur-, Sequenz- und Datenflussdiagramme in einem Diagrammtool wie Excalidraw, draw.io oder Mermaid. Verlinke immer die Quelldatei oder halte den Mermaid-Code im Dokument, damit die nächste Person das Diagramm aktualisieren kann.

Annotiere den Ist-Zustand, damit Reviewer das Problem in 5 Sekunden sehen

Ein nackter Screenshot lässt Reviewer nach dem Problem suchen. Markiere ihn mit ein paar Werkzeugen:

• Zählernummern, die zur nummerierten Problemliste im Dokument passen.
• Ein Pfeil auf den genauen Fehler oder das genaue Bedienelement.
• Eine Hervorhebung auf der Zahl, auf die es ankommt, etwa der Zeilenzahl.
• Ein kurzer Textkommentar mit dem einen Fakt, den ein Reviewer braucht, etwa „p95 41 s“.

Zum Aufnehmen reichen die eingebauten Tastenkürzel: ⌘ + Shift + 4 auf dem Mac (Apple Support) oder Win + Shift + S unter Windows (Microsoft Support). Danach setzt du die Markierungen in einem beliebigen Editor oder im kostenlosen Tool zur Bildannotation. Für einheitliche Farben und Markierungsgrößen über mehrere Dokumente hinweg folgst du den Annotationsstandards im Leitfaden für Screenshots in technischer Dokumentation. Dieselbe Methode mit nummerierten Markierungen aus Schritt-für-Schritt-Anleitungen funktioniert auch für Problemlisten.

Zeig geplante UI-Änderungen nebeneinander

Stell den aktuellen und den geplanten Bildschirm in gleicher Größe und mit denselben Demodaten nebeneinander. Zieh Hervorhebungsrahmen nur um das, was sich ändert. Die geplante Variante kann ein Figma-Frame oder ein Screenshot eines Prototyps sein.

Schwärzen, bevor du einfügst

Design Docs werden breit geteilt und leben jahrelang. Bevor ein Screenshot hineinkommt, deckst du Kunden-E-Mails, Account-IDs, Tokens, interne Hostnamen und IP-Adressen mit einem vollflächigen, undurchsichtigen Kasten ab. Weichzeichnen und Verpixeln lassen sich teilweise rückgängig machen, wie der Leitfaden zum Schwärzen von Text in Screenshots zeigt. Nutz sie nur für unkritische Details, etwa einen Browser-Tab im Hintergrund.

Text bleibt Text

Ein Screenshot eines Fehlerdialogs oder Logs ist nicht durchsuchbar, und niemand kann die Request-ID daraus kopieren. Lass eine Texterkennung (OCR) über den Screenshot laufen (das kostenlose Tool zum Extrahieren von Text aus Bildern eignet sich dafür) und füg den Text in einen Codeblock ein. Behalte den Screenshot nur, wenn das Layout wichtig ist.

Kurze GIFs für Abläufe und wo Bilder hingehören

Für einen Ablauf, der sich in einem einzelnen Bild schwer zeigen lässt, etwa einen hängenden Export, nimm ein GIF von 5 bis 10 Sekunden auf. Es gibt Anleitungen für die GIF-Aufnahme auf dem Mac und die GIF-Aufnahme unter Windows.

Halte es mit dem kostenlosen GIF-Kompressor klein, bevor du es anhängst.

Speicher Bilder zusammen mit dem Dokument. Bette die Bilddateien direkt in Google Docs, Confluence oder Notion ein oder committe sie ins Repo neben die Markdown-Datei, zum Beispiel in docs/design/img/. Ein Cloud-Link zum Teilen ist gut, um einen Screenshot schnell in einen Review-Thread oder den Chat zu werfen. Als dauerhafte Bildquelle im Dokument taugt er nie, denn gehostete Uploads können ablaufen.

Für Vergleichsbeispiele auf öffentlichen Seiten, etwa die öffentliche Doku eines anderen Produkts oder deine eigene Statusseite, zeigt ein Vollseiten-Screenshot die ganze Seite in einem Bild. Sieh dir dazu die Anleitungen für Vollseiten-Screenshots auf dem Mac und unter Windows an. Für Admin-Bereiche hinter einem Login, Staging und interne Tools nimmst du stattdessen einen Bereich oder ein Fenster auf.

Wenn du jede Woche Screenshots für Dokus aufnimmst und markierst, bündelt ScreenSnap Pro diese Arbeit in einer App für Mac und Windows. Es hat Werkzeuge für Zähler, Pfeile, Hervorhebungen und Text, ein deckendes Rechteck zum Schwärzen und OCR, um Fehlertext aus einem Screenshot zu kopieren. Mit der Pin-Screenshot-Funktion schwebt der Screenshot vom Ist-Zustand auf dem Bildschirm, während du das vorgeschlagene Design schreibst. Außerdem nimmt es GIFs auf und erfasst vollständige öffentliche Webseiten per URL. Architekturdiagramme zeichnet es nicht, die bleiben also in deinem Diagrammtool. Sieh dir an, was es kostet.

So bringst du dein Design Doc durchs Review

Im Review zeigt ein Design Doc, was es wert ist. Mach es in zwei Durchgängen: zuerst asynchrone Kommentare, dann ein kurzes Meeting für alles, was übrig bleibt.

Wen du einlädst: einen Owner für jede Abhängigkeit, die das Design berührt, die SRE- oder On-Call-Leitung, Security, wenn personenbezogene Daten oder Login-Abläufe betroffen sind, und den QA-Lead. Markiere 3 bis 6 Leute als Pflicht-Reviewer und alle anderen als optional.

Zuerst asynchrone Kommentare: Teil das Dokument mit einer Frist von zwei oder drei Arbeitstagen. Bitte um Kommentare zu konkreten Zeilen. Google Docs unterstützt das, und Confluence mit Inline-Kommentaren auch. Wenn das Dokument im Repo liegt, ist das Pull-Request-Review der Kommentar-Thread.

Jeden Thread lösen oder vertagen: Jeder Thread endet auf eine von zwei Arten. Entweder ändert sich das Dokument und der Thread wird als gelöst markiert, oder die Frage wandert mit Owner und Fälligkeitsdatum in die Tabelle der offenen Fragen.

Eine Agenda für ein 30-minütiges Review:

1. Fünf Minuten: Der Autor fasst Problem, Ziele und Nicht-Ziele noch einmal zusammen.
2. Fünfzehn Minuten: offene Threads, das größte Risiko zuerst.
3. Fünf Minuten: ein Check, ob die Alternativen echt waren.
4. Fünf Minuten: die Entscheidung (freigeben, mit Änderungen freigeben oder überarbeiten) und die nächsten Schritte.

Reviewer-Checkliste mit den 8 Fragen, die Reviewer stellen:

1. Kann ich das Problem nach der ersten Seite in einem Satz wiedergeben?
2. Sind die Nicht-Ziele ausdrücklich genannt, und stimme ich ihnen zu?
3. Passen die Belege zum Ist-Zustand zu dem, was ich in Produktion sehe?
4. Wurden mindestens zwei echte Alternativen erwogen, mit ehrlichen Gründen für ihre Ablehnung?
5. Was passiert, wenn eine Abhängigkeit langsam oder ausgefallen ist?
6. Wohin fließen personenbezogene oder geheime Daten, und wie lange werden sie aufbewahrt?
7. Woran erkennen wir, dass es in Produktion funktioniert?
8. Können wir zurückrollen, und wie schnell?

Warum Design Docs im Review scheitern:

• Keine Nicht-Ziele, also wird das Meeting zur Verhandlung über den Umfang.
• Keine Alternativen, also schlagen Reviewer sie live vor, und die Diskussion beginnt von vorn.
• Ein unklarer Ist-Zustand, also streiten die Leute über Fakten statt über das Design.
• Eine Textwand ohne Diagramm und ohne Screenshots, an denen sich die Diskussion festhalten kann.
• Veraltete Screenshots, bei denen sich die Oberfläche nach der Aufnahme geändert hat und Reviewer dem Rest nicht mehr trauen.

So bleibt das Design Doc nach dem Launch aktuell

Die meisten Design Docs veralten in der Woche, in der das Feature live geht. Vier Gewohnheiten halten deins nützlich:

• Aktualisiere den Status. Setz ihn auf Umgesetzt oder auf Ersetzt, mit einem Link zum neueren Dokument.
• Halte spätere Entscheidungen als ADRs fest. Jedes ADR verlinkt zurück auf das Design Doc, damit die Begründung verbunden bleibt. Der Leitfaden zu interner Dokumentation enthält eine Vorlage für Entscheidungsprotokolle.
• Mach aus dem „Ist-Zustand“ einen „Stand der Umsetzung“. Ergänze einen kurzen Abschnitt dazu, was sich gegenüber dem Plan geändert hat und warum.
• Verlinke es dort, wo Leute suchen. Nimm das Dokument in die README auf, in die Pull Requests, die es umsetzen, und in die Release Notes zum Launch.

Häufig gestellte Fragen

Wie schreibst du ein Software-Design-Dokument?

Stimm zuerst Problem, Ziele und Nicht-Ziele mit den wichtigsten Stakeholdern ab und zeig dann den Ist-Zustand mit Belegen. Entwirf das Design mit mindestens zwei Alternativen, mach ein asynchrones Review und aktualisiere den Status nach dem Launch. Der Abschnitt mit der Schritt-für-Schritt-Anleitung deckt alle sieben Schritte ab.

Wie strukturierst du ein Design Doc?

Nutz 10 Abschnitte in dieser Reihenfolge: Kopfbereich, Kontext und Problem, Ziele und Nicht-Ziele, Ist-Zustand, vorgeschlagenes Design, erwogene Alternativen, Sicherheit und Performance, Teststrategie, Rollout und Rollback sowie Risiken mit offenen Fragen. Für kleine Änderungen reicht ein One-Pager mit Problem, Zielen, Design, Alternativen und Rollout.

Was macht ein gutes Design Doc aus?

Ein gutes Design Doc nennt seine Abwägungen und die verworfenen Optionen, listet klare Nicht-Ziele auf und belegt den Ist-Zustand mit Screenshots, Metriken und Tickets. Außerdem ist es kurz genug für ein Review in einer Sitzung, mit einem Diagramm und einem klaren Status ganz oben.

Gibt es ein Beispiel für ein System-Design-Dokument?

Ja. Das Beispiel zu asynchronen CSV-Exporten oben ist ein gekürztes, ausgefülltes Design Doc mit Zielen, annotierten Screenshots, einem Architekturdiagramm, Alternativen, Risiken und einem Rollout per Feature Flag. Weitere echte Dokumente von Engineering-Teams findest du auf designdocs.dev.

Was ist ein PDD-Dokument?

PDD steht meist für ein Process Definition Document in der Robotic Process Automation (RPA). Es bildet einen manuellen Geschäftsprozess Schritt für Schritt ab, bevor ein Bot ihn übernimmt. Manche Produktteams nutzen PDD auch für ein Product Design Document. Keins von beiden ist ein Software-Design-Dokument, das erklärt, wie Engineers ein System bauen werden.

Welche Beispiele für Softwaredokumentation gibt es?

Typische Arten sind Anforderungsdokumente (PRD und SRS), Software-Design-Dokumente, ADRs, API-Referenzen, READMEs, Runbooks, Testpläne, Release Notes und Benutzerhandbücher. Jede dient einem anderen Leser in einer anderen Phase. Für die Business-Seite deckt der Leitfaden zur Prozessdokumentation wiederkehrende Abläufe ab.

Hat Google Docs eine Vorlage für Design Docs?

Google Docs hat eine Vorlagengalerie unter Datei > Neu > Aus Vorlagengalerie. Sie konzentriert sich aber auf allgemeine Dokumente wie Projektvorschläge, Roadmaps und Besprechungsnotizen, nicht auf Design Docs fürs Engineering. Schneller geht es, wenn du die Markdown-Vorlage oben mit „Aus Markdown einfügen“ einfügst, nachdem du Markdown unter Tools > Einstellungen aktiviert hast.

Starte dein nächstes Design Doc mit der Vorlage

Kopier die Vorlage, schreib zuerst Problem und Ziele und hol dir früh Zustimmung, bevor du irgendetwas entwirfst. Ergänze annotierte Screenshots für den Ist-Zustand, schwärze, bevor du einfügst, und halte das Dokument nach dem Launch aktuell.

Wenn du ein Tool für die Screenshot-Seite dieser Arbeit willst: ScreenSnap Pro ist ein einmaliger Kauf für 34 $, mit 1 Lizenz für 2 Computer (Mac oder Windows). Zu den Preisen.