German Technical Writing

German Technical Writing

Natural German technical register for German-audience artifacts. Prevents English-first composition plus phrase-by-phrase translation, which produces grammatically correct German that reads as DeepL-output to native readers.

Process

1. Compose in German directly, not by translating. Restart if you catch yourself drafting English first. 2. Self-review each sentence against references/anti-patterns.md. 3. Apply the lexicon — canonical verbs and loanword gender: references/lexicon.md. 4. Match register — Präsens-Indikativ, impersonal voice, no first-person: references/register.md. 5. If unsure, ask — don't guess.

Top anti-patterns

Full ~60-entry catalogue plus pseudo-anglicisms and idiom calques in references/anti-patterns.md. Worked pair-examples in references/examples.md.

Two opposite traps — apply both disciplines

Two failure modes — over-applying one drives you into the other:

1. Anglicism (verb-level): keeping English when German is canonical. Test failt → schlägt fehl. Fehler triggern → Fehler auslösen. The table above and anti-patterns.md target this. 2. Calque / overcorrection (compound-noun-level): translating English when the loanword is canonical. Wurzelursache → Root Cause. Wettlaufbedingung → Race Condition. Speicherleck → Memory Leak. See anti-patterns.md ("Compound-noun calques") and lexicon.md ("Debugging / Postmortem / Analysis").

Decision rule for nouns: if a native German developer would say the term verbatim in a code review or stand-up, keep it English. The litmus test isn't "does a German equivalent exist?" — it's "do German engineers actually use it in everyday speech?" A German form that sounds like a textbook chapter title is a calque.

Absorbing "use German verbs" without "keep loanword nouns" produces DeepL-grade output. Apply both simultaneously.

Scope note

Commit messages, MR/PR descriptions, release notes and internal IT-project tickets (Netresearch: NRS, NRT, SRV\, IO\, LIC) are English — skip them. This skill governs how to write German, never whether German is the right choice.

Anti-Patterns — False Friends in German Technical Writing

Catalogue of literal English→German translations that read as anglicisms in professional German technical prose, paired with the natural technical phrasing.

How to use

Search by English concept or by the wrong-form you're tempted to write. Each row explains why the wrong form reads as anglicism — grammatical but foreign — and which form is established in German dev writing.

Verbs — Exceptions & Errors

Verbs — Tests & Builds

Verbs — Data Flow & Control

Verbs — Git & VCS

Nouns & Adjectives

Sentence structure

Compound-noun calques (the "Wurzelursache" trap)

These are the opposite of the verb-level anglicisms above. Writers who internalize "use German verbs" tend to over-correct and start translating English compound technical terms that should stay as loanwords. The result is grammatically perfect German that sounds like DeepL output to a native engineer because no German developer ever utters those translations.

Decision rule

If a native German developer would say the term verbatim in a code review or stand-up, keep it English. The litmus test isn't "does a German equivalent exist?" — Duden has German for nearly everything. The test is: "does any German engineer actually use the German equivalent in everyday speech?" If the German form sounds like a textbook chapter title, it's a calque.

Two opposite errors — keep them straight

This file catalogues two distinct failure modes, and over-applying one drives you into the other:

1. Anglicism (verbs): keeping English when German is canonical. Test failt → schlägt fehl. Fehler triggern → Fehler auslösen. The verb tables above target this. 2. Calque (compound nouns): translating English when the loanword is canonical. Wurzelursache → Root Cause. Wettlaufbedingung → Race Condition. The compound-calque table above targets this.

Both disciplines apply simultaneously. Writers who absorb only the first drift into the second.

Pseudo-anglicisms to avoid

These are German "English" words that don't exist in English or mean something else:

• Handy for mobile phone — acceptable in general German but never in tech writing (use Smartphone)
• Beamer for projector — avoid in tech writing (use Projektor)
• Shooting for photo session — marketing-speak, not tech
• Oldtimer for vintage car — irrelevant but beware the pattern

When to break the rules

Use anglicisms deliberately when:

• Quoting someone else's exact words
• Writing chat messages to a team that already uses the term
• In code-adjacent contexts where English identifier names need context ("the callback wird gecallt" sounds less weird than "der callback wird aufgerufen" if the discussion is heavily about the literal identifier)

But always flag it consciously — not as a default.

Examples — Bad vs. Good

Real paired cases from past Jira tickets and team-chat announcements. Each pair shows the anglicism-laden original, the rewrite, and why the rewrite works.

Case 1 — The opening incident

Bad (OROSPD-692 comment, 2026-04-24):

Ein bare get würde mit BadMethodCallException zur Laufzeit brechen. Ein Regressionstest führt den Provider durch den Decorator, damit ein Rename in die Falle zurück von Unit-Tests gefangen wird.

Problems:

1. "ein bare get" — bare is not a German word in this sense. Use "ein unqualifiziertes `get`" or "ein nacktes `get`". 2. "würde … brechen" — Konjunktiv II without counterfactual + brechen for "break code". Should be Indikativ "wirft" (the unqualified call does throw at runtime — not hypothetically). 3. "in die Falle zurück" — garbled calque of "back into the trap". German has no equivalent idiom here. 4. "gefangen" — literal "caught". Tests erkennen, decken auf, or fangen ab.

Good:

Ein unqualifiziertes get wirft zur Laufzeit eine BadMethodCallException. Der Regressionstest schickt den Provider durch den Decorator, damit ein späterer Rename direkt in den Unit-Tests auffliegt — ohne Decorator würde ein Umbenennen erst im Behat-Lauf sichtbar.

Why it works:

• Indikativ for fact (wirft), Konjunktiv II only for the explicit counterfactual ("ohne Decorator würde ...")
• unqualifiziertes is the technical term for method calls without context
• auffliegt is idiomatic German for "a bug gets caught" in colloquial tech speech — alternative: erkannt wird
• The ohne Decorator würde ... clause provides the missing motivation that the original garbled away

Case 2 — Test failure description

Bad:

Der Test ist gefailt weil die Fixture empty war und das System in einen bad state endete.

Problems:

• gefailt — pure anglicism
• empty — untranslated English
• bad state — untranslated English
• endete — enden is literal for "end up"

Good:

Der Test ist fehlgeschlagen, weil die Fixture leer war und das System in einem inkonsistenten Zustand landete.

Why:

• fehlgeschlagen — canonical verb for test failure
• leer — German word exists, use it
• inkonsistenter Zustand — established technical phrasing for "bad state"
• landen — the idiomatic verb when a process arrives somewhere unintended

Case 3 — Jira comment: fix explanation

Bad:

Der Bug ist gefixt wo die Exception gecatched wurde aber nicht rethrown, sodass der Error silent war. Ich habe das gehandled indem ich den Handler refactored habe.

Problems:

• Stacked Denglisch with no reason: gefixt, gecatched, rethrown, silent, gehandled, refactored
• First person ("Ich habe") in a Jira comment that belongs in shared ticket history
• "wo" as relative pronoun for a thing is colloquial and wrong here
• silent applied to Error — English idiom that doesn't transfer

Good:

Die Exception wurde zwar abgefangen, aber nicht erneut geworfen — der Fehler blieb dadurch unsichtbar. Der Handler ist umgestellt, sodass die Exception nach dem Logging weitergereicht wird.

Why:

• abgefangen (proper verb), erneut geworfen (re-throw), unsichtbar (silent → invisible, the natural equivalent)
• Impersonal — no "ich"
• Describes the outcome ("der Handler ist umgestellt"), not the author's process
• weitergereicht is the established verb for passing an exception up the stack

Case 4 — Jira description problem statement

Bad:

Das Issue ist dass der Service immer null returned wenn die DB empty ist, was einen NullPointer trigger im Frontend bedeutet. Wir müssen das handeln.

Problems:

• returned, empty, trigger, bedeutet (calqued from "means")
• Issue is fine as loanword but das Problem would also work
• handeln = "to trade/act", not "to handle errors"
• First person ("Wir müssen") in a problem statement

Good:

Der Service gibt bei leerer Datenbank null zurück. Im Frontend löst das eine NullPointerException aus. Die Fehlerbehandlung muss ergänzt werden.

Why:

• gibt … zurück — canonical German for return
• löst … aus — canonical German for trigger
• Three short sentences instead of one rambling one
• Impersonal "muss ergänzt werden" instead of first-person "Wir müssen"

Case 5 — Status update comment

Bad:

Update: Ich habe heute das Issue debugged und gefunden dass der Root Cause die DataProviderDecorator Regex ist. Der bare get Name wird gerejected. Ich fixe das jetzt indem ich die Method zu getPimField renamen.

Problems:

• First person throughout
• debugged, gerejected, bare, renamen, Root Cause unsteady
• "Ich fixe das jetzt indem ich ... renamen" — verb placement + infinitive mix
• Stream-of-consciousness structure; not scannable

Good:

Status-Update: Die Ursache liegt in der Regex /^(get|has|is)(.+)$/i des DataProviderDecorator — der unqualifizierte Methodenname get wird abgelehnt. Fix: Methode wird auf getPimField umbenannt.

Why:

• Impersonal passive throughout
• Concrete detail (the actual regex pattern) replaces vague "Root Cause"
• Two sentences: diagnosis, then fix. Scannable.
• Italic "Status-Update:" as a lead-in works in Jira wiki markup

Case 6 — Deployment announcement

Bad:

Heads up: Der neue Release geht heute abend live. Wer noch MRs am draft hat sollte merged haben bis 18 Uhr sonst slippt das in die nächste Deploy Window.

Problems:

• Heads up, slippt, Window — English idioms breaking rhythm
• "gerne" missing — announcements like this tend to be clipped to the point of rudeness
• Mixed sentence structure

Good:

Hinweis: Das nächste Release geht heute Abend live. Offene MRs müssen bis 18:00 Uhr gemergt sein, sonst verschieben sie sich auf den nächsten Deploy.

Why:

• Hinweis is the German equivalent of "heads up" in an announcement register
• verschieben sich replaces slippt — proper German
• "nächsten Deploy" — Deploy is accepted loanword, use it without Window

Meta-observation

Across these cases, the repeating failure modes are:

1. First person slipping into artifacts — chat habits bleeding into persistent text 2. Verb-cognate translation — grabbing the first German verb that sounds like the English one, instead of the established technical one 3. Idiom calquing — translating an English idiom word-for-word when German has no equivalent (the idiom has to be dropped or reformulated) 4. Untranslated adjectives — empty, silent, bare, flaky, green — German has all of these, the writer just forgot to switch 5. Konjunktiv II for non-hypotheticals — adding würde to soften when the sentence should be blunt Indikativ

When reviewing your own German draft, scan for these five patterns specifically. One pass is usually enough.

Technical Lexicon — Preferred German Forms

Table of technical terms with gender, preferred form, and usage notes. Use this when you need to pick between two candidate phrasings for a concept.

How this list is organized

• EN term — the English concept
• DE form — preferred form with article (where noun)
• Register — accepted Denglisch loanword (use as-is), native German (preferred in formal writing), both (either works)
• Notes — gotchas, gender, pluralization

Exceptions & Error Handling

Tests

Version Control & Git

CI / CD / Build

HTTP / APIs

Frontend / UI

Data / Persistence

Architecture / Patterns

Common verbs — technical register

Articles for ambiguous loanwords

These get mistakes most often. Fix the article first:

• der Commit, der Rebase, der Merge, der Branch, der Build, der Bug, der Fix, der Patch, der Hook, der Mock, der Stub, der Wrapper, der Decorator, der Provider, der Service, der Controller, der Token, der Header, der Callback, der Listener, der State, der Request, der Endpoint, der Cache, der Index, der Timeout (or das), der Retry
• die Pipeline, die Exception, die Fixture, die Assertion, die Response, die Session, die Migration, die Query, die Prop, die Factory, die Komponente, die Schnittstelle
• das Interface, das Feature, das Event, das Ticket, das Issue, das Template, das Deployment, das Staging, das Logging, das Monitoring, das Framework, das Caching, das Routing, das Rendering, das Payload, das Refactoring, das Repository, das Schema

Debugging / Postmortem / Analysis

These are the terms most prone to the calque-overcorrection trap. Native German engineers say all of these as English loanwords; translating them produces DeepL-output that no developer would speak.

Calque check

Before writing a German compound noun in tech prose, ask: would I say this German word out loud in a code review with a German-speaking team? If the answer is "no, I'd say the English term," keep the loanword. The litmus test isn't dictionary existence — Duden has translations for nearly everything. The test is everyday-engineering-speech use.

When no entry exists

If a term isn't here:

1. Check whether it's in the Duden online (duden.de) — if yes, use that gender/spelling 2. Check how the Microsoft German Style Guide handles it 3. If still unclear, prefer the native German form in written text, the loanword in chat 4. If truly ambiguous, ask the user

Register — Tense, Voice, Person, and Artifact-Specific Conventions

Register is the biggest single driver of whether German technical prose reads as native or translated. Use this reference when composing longer artifacts: Jira descriptions and comments, internal German-language wiki pages, RFC/spec documents, and team-chat messages to German-speaking colleagues.

Not in scope: commit messages, MR/PR descriptions, and release notes — at Netresearch and most agencies delivering customer projects, those are written in English by team convention regardless of the team's native language.

Tense

Default: Präsens-Indikativ. Use it for describing what code does, what a system behaves like, what a ticket is about.

• ✅ "Der Service wirft bei fehlendem Feld eine Exception."
• ❌ "Der Service würde bei fehlendem Feld eine Exception werfen." (Konjunktiv II without counterfactual — calqued from English "would throw")

Konjunktiv II only for real hypotheticals. Counterfactuals, proposals, "if we did X", forward-looking plans:

• ✅ "Wenn wir die Cache-TTL auf 10 Minuten senken würden, würde der ES-Index seltener neu aufgebaut."
• ✅ "Ohne den Decorator-Layer würde ein Rename erst im Behat-Lauf sichtbar." (counterfactual — the Decorator layer exists, we're describing the absence case)

Perfekt for completed work done: Acceptance criteria, status updates, Jira-comment narrations.

• ✅ "Die Lock-Datei ist aktualisiert, die Pipeline läuft grün."
• ✅ "Der Import-Pfad ist umgestellt; die alte Klasse ist entfernt."

Präteritum almost never in tech writing. It's literary/narrative. Never use it in Jira text.

• ❌ "Der Test schlug fehl, weil die Fixture leer war." (sounds like a novel)
• ✅ "Der Test ist fehlgeschlagen, weil die Fixture leer war." (Perfekt — natural tech prose)

Voice

Active preferred when an actor is identifiable. Pick it when you're describing what a specific service/test/user does.

• ✅ "Der PricingStorageIsolator rebuildet die Combined-Price-Lists aus den raw-Rows."
• ✅ "Das Fixture-Loader liest die YAMLs aus tests/Fixtures/."

Passive for system behavior where the actor is irrelevant or diffuse. Jira ticket descriptions often benefit from passive because they describe outcomes, not actors.

• ✅ "Die Exception wird zur Laufzeit geworfen."
• ✅ "Die PriceListToCustomer-Rows werden beim PricingStorageIsolator-Lauf neu aufgebaut."

Avoid mixing active and passive in a single flow. Pick one per paragraph for parallelism.

Never use "man" in technical writing for a concrete actor. It's acceptable in generic statements ("man kann X auch über Y erreichen") but clunky when a subject is identifiable.

• ❌ "Man muss das Behat-Baseline neu aufbauen."
• ✅ "Das Behat-Baseline muss neu aufgebaut werden."

Person

No first person in artifact text. Ever. "Ich", "wir", "uns" belong in informal chat replies and 1:1 communication — not in Jira descriptions or internal wiki/spec pages.

• ❌ "Wir haben den Bug gefixt."
• ✅ "Der Bug ist behoben." (Perfekt-Passiv)
• ✅ "Der Fix ist enthalten in Commit abc1234." (if you need to name it)

Second person only in user-facing documentation aimed at a reader. Use Sie-Form in product-facing documentation, Du-Form in internal wiki/team docs (HMKG team uses Du).

• ✅ (HMKG team wiki) "Achte darauf, dass der Branch auf develop basiert, bevor du merged."
• ✅ (external customer docs) "Melden Sie sich unter /admin an und navigieren Sie zu ..."

Artifact-Specific Conventions

Jira Issue Description

Structure:

h2. Problem
[What is broken/missing/needed. Impersonal, present tense, 2-4 sentences max.]

h2. Ziel
[What the solution should achieve. Impersonal, present or future, 1-2 sentences.]

h2. Akzeptanzkriterien
* [Bullet list, each item passive or imperative infinitive]
* [...]

h2. Out of Scope
* [What this ticket explicitly does NOT cover]

h2. Abhängigkeiten
* Benötigt: [ticket keys]
* Blockiert: [ticket keys]
* Parent Epic: [key]

Style:

• Impersonal throughout — no "ich/wir"
• Present tense for the problem description (it is broken now)
• Bullets in parallel grammatical form (all noun phrases or all imperative verbs, not mixed)

Jira Comment

• Start with context in one line (MR link, CI status, commit SHA)
• Use h3. headings, not h2. (comments are sub-content)
• Tables for feature/test enumerations (|| Column || Column || header, | cell | cell | rows)
• Code elements in {{monospace}}
• Closing: facts + next action, no hedging ("Hoffen wir mal", "Scheint zu funktionieren" — cut)

Commit messages, MR/PR descriptions, and release notes — not in scope

At Netresearch and most agencies delivering customer projects, commit messages, MR/PR descriptions, and release notes are all written in English by team convention regardless of the team's native language. Do not apply this skill's guidance to those artifacts — if a German version crosses your desk, flag it as off-convention rather than polish the German.

Internal German Wiki / Spec Pages

• Sie-Form for customer-facing docs; Du-Form for internal team wiki (HMKG convention)
• Impersonal voice in specification sections; direct voice acceptable in how-to sections
• Heading hierarchy: # for page title, ## for major sections, ### for subsections
• Technical terms in the established lexicon — same rules as Jira prose

Sentence Length

German allows longer sentences than English, but technical prose in Jira contexts should stay short. Rule of thumb:

• Ideal: 10–15 words per sentence
• Acceptable: up to 25 words
• Hard stop: 35+ words means split it

The reason: Jira readers skim. Long Verbalketten-Sätze are where anglicisms hide because the writer loses the thread halfway through.

Compound Nouns

German loves compound nouns. Technical writing leverages this, but beware overstacking:

• ✅ "Produkt-Konfigurations-Attribut" (3 elements, readable)
• ⚠️ "Produkt-Konfigurations-Attribut-Validierung" (4 elements, starting to strain)
• ❌ "Produkt-Konfigurations-Attribut-Validierungs-Service" (5 elements — split with prepositions)
• → "Service zur Validierung von Produkt-Konfigurations-Attributen"
• → "Validierungs-Service für Produkt-Konfigurations-Attribute"

Hyphenation rule: connect with - when at least one component is a loanword (Exception-Handler, PriceList-Rebuild, CI-Pipeline). Pure German compounds can omit hyphens (Konfigurationsattribut) but hyphens are always safe for readability.

Orthography Minimums

Never substitute these with ASCII:

• ß — "weiß", "Fuß", "groß", "Maß". Never write "weiss", "Fuss". (exception: Swiss German drops ß — not our context)
• ä ö ü — "Qualität", "Überprüfung", "Änderung". Never "ae/oe/ue" in normal text.
• „…" — German quotation marks. In Jira markup or code contexts, straight quotes "..." are fine. In plain prose, use „…" for nested quotes.

Capitalization:

• All nouns capitalized (the default German rule — don't forget)
• Verbs used as nouns capitalized: "das Rebuilden der Combined-Price-Lists"
• Adjectives normally lowercase unless nominalized: "das Wichtigste ist X" (nominalized), "der wichtige Schritt" (attribute)

Checklist — self-review pass

Before posting any German artifact longer than one sentence, read through it once and ask:

1. ☐ Is every verb drawn from the German technical lexicon, not translated from English? 2. ☐ Is the tense Präsens-Indikativ (default) or justified Konjunktiv/Perfekt? 3. ☐ Is there any first-person ("ich", "wir") that should be impersonal? 4. ☐ Is every sentence under 25 words? 5. ☐ Are compound nouns split at ≤3 elements or with prepositions beyond that? 6. ☐ Are ß/ä/ö/ü intact? 7. ☐ Does any sentence contain a calqued English idiom ("am Ende des Tages", "low-hanging fruit", "auf derselben Seite")? 8. ☐ If bullet points: are they in parallel grammatical form?

If any check fails, fix it before posting.