Entwicklung

Vorlage für technische Spezifikation in Markdown

Diese Vorlage für technische Spezifikationen ist ein durchgearbeitetes Beispiel, kein leeres Formular. Sie beschreibt einen Zahlungsdienst und zeigt, wie ein Diagramm, eine Formel und ein Codebeispiel in einem Dokument zusammenwirken. Ersetze den Inhalt durch dein eigenes Design und behalte die Struktur bei.

Diese Vorlage im Editor öffnen

Kategorie: Entwicklung
Standardstil: Technisch

Wann du sie brauchst

Schreib eine Spezifikation, bevor du etwas baust, dem mehr als eine Person zustimmen muss. Entwicklerinnen lesen sie, um das Design zu prüfen, Produkt- oder QA-Kolleginnen lesen sie, um zu erfahren, was ausgeliefert wird. Eine PDF-Version passt zu Design-Reviews, zur Freigabe durch Kunden und zu jedem Archiv, in dem das Dokument auch Jahre später gleich aussehen soll.

Was enthalten ist

Ein Überblick mit Ausfüllfeldern für Projekt und Verantwortliche, gefolgt von einem Mermaid-Sequenzdiagramm des Ablaufs.
Ein Abschnitt zum Wiederholungsbudget mit einer TeX-Formel und einem TypeScript-Beispiel in einem hervorgehobenen Codeblock.
Ein manueller Seitenumbruch vor der Liste offener Fragen, damit sie auf einer neuen Seite beginnt.

Tipps für ein besseres Dokument

Stelle das Ablaufdiagramm vor die Details. Wer die Abfolge zuerst versteht, liest die übrigen Abschnitte schneller und stellt bessere Fragen.
Halte offene Fragen in der Spezifikation, bis jemand sie beantwortet, und verschiebe jede Antwort dann in den passenden Abschnitt. Bei einer langen Spezifikation ergänze ein Deckblatt und ein Inhaltsverzeichnis.

Vorlagenvorschau

Spezifikation Zahlungsdienst

Projekt: Projekt oder Thema Verantwortlich: Dein Name

Überblick

Der Zahlungsdienst nimmt eine Bestellung entgegen, belastet die Karte und speichert das Ergebnis. Anfragen sind 24 Stunden lang idempotent.

Ablauf

sequenceDiagram
  participant App
  participant API
  participant Stripe
  App->>API: POST /charge
  API->>Stripe: create PaymentIntent
  Stripe-->>API: status
  API-->>App: receipt

Wiederholungsbudget

Jeder Client darf mit exponentiellem Backoff erneut versuchen, wobei die Wartezeit nach Versuch $n$ gilt als

w_n = \min(2^n \cdot 250\,\text{ms},\ 8\,\text{s})

Beispiel

export const charge = async (order: Order) => {
  const intent = await stripe.paymentIntents.create({ amount: order.total });
  return { id: intent.id, status: intent.status };
};

Offene Fragen

Speichern wir die letzten vier Ziffern?
Welche Währungen zuerst?

Ausfüllfelder wie dein Name und das Datum werden ersetzt, sobald du die Vorlage im Editor öffnest.