Kommentare in der Technischen Dokumentation: Do’s & Don’ts

Sinn und Zweck von Kommentaren bei technischer Dokumentation

In der technischen Dokumentation dienen Kommentare als wertvolles Kommunikationswerkzeug zwischen Autoren und Reviewern. Mit gut platzierten Kommentaren können Sie Feedback geben, Unklarheiten anmerken oder Verbesserungsvorschläge machen, ohne den veröffentlichten Text selbst zu verändern.

Gerade in kollaborativen Schreibprozessen helfen Kommentare dabei, frühzeitig Probleme oder Unstimmigkeiten zu erkennen und gemeinsam zu beheben. Ähnlich wie Code-Reviews in der Softwareentwicklung helfen, Fehler zu finden und Code-Qualität zu sichern. Neben der Fehlerfindung unterstützen Reviews auch den Wissensaustausch im Team:

• Neue Mitglieder erhalten Feedback zu Konventionen und Best Practices,

• Wissen wird geteilt,

• eine Kultur der Qualität entsteht

Genauso fördern Kommentare in Dokumenten eine solche Qualitätskultur. Sie erleichtern es:

• konsistenten Schreibstil sicherzustellen,

• offene Fragen zu klären,

• und gemeinsames Verständnis über den Inhalt zu schaffen.

Ein weiterer Zweck von Kommentaren ist das Festhalten von To-dos oder offenen Punkten direkt im Text. Anstatt sich auf Ihr Gedächtnis zu verlassen oder separate Notizen zu führen, schreiben Sie in den Entwurf einfach:

//  TODO: Diagramm aktualisieren, sobald neue Daten vorliegen

Solche internen Notizen gehen nicht in die veröffentlichte Doku ein, erinnern aber alle Beteiligten daran, welche Stellen noch bearbeitet werden müssen.

Insgesamt machen sinnvoll eingesetzte Kommentare den Dokumentationsprozess effizienter: Sie kommunizieren direkt am Text, was verbessert oder geprüft werden sollte, und sorgen dafür, dass beim Review nichts übersehen wird. Durch die klar sichtbaren Hinweise können Reviewer genau nachvollziehen, welche Gedanken sich der Autor an bestimmten Stellen gemacht hat, oder wo er Rückmeldung benötigt. Das Ergebnis sind präzisere, konsistentere technische Dokumente – erstellt in einem Klima offener Kommunikation.

Do’s und Don’ts hilfreicher Kommentare

Nicht jeder Kommentar ist per se hilfreich. Es kommt darauf an, wie Sie kommentieren. Beachten Sie daher einige Grundregeln, damit Ihr Feedback konstruktiv und willkommen ist:

Do’s – das sollten Sie tun:

• Klar und konkret kommentieren: Sprechen Sie konkrete Stellen im Dokument an und erklären Sie präzise, was Ihnen auffällt. Zum Beispiel statt „Unklar“ besser „Der Abschnitt zur Installation ist unklar – warum muss man zuerst X tun?“. Je spezifischer Ihr Kommentar, desto leichter kann der Autor darauf eingehen.

• Sachlich und respektvoll bleiben: Formulieren Sie in einem höflichen, professionellen Ton. Kritisieren Sie den Inhalt, nicht die Person. Fokussieren Sie sich auf die Dokumentation selbst und nicht auf deren Verfasser. Durch sachliche, respektvolle Kommentare signalisieren Sie, dass es um die Verbesserung des Dokuments geht, nicht um persönliche Kritik.

• Konstruktive Vorschläge machen: Wenn Sie ein Problem aufzeigen, bieten Sie nach Möglichkeit einen Verbesserungsvorschlag an. Ein hilfreicher Kommentar könnte z. B. lauten: „// Suggestion: Vielleicht wäre hier ein Codebeispiel sinnvoll, um den Schritt zu verdeutlichen.“ So geben Sie dem Autor eine Richtung, anstatt nur auf Mängel hinzuweisen.

• Lob aussprechen, wo es verdient ist: Scheuen Sie sich nicht davor, positive Aspekte hervorzuheben. Ehrlich gemeinte Anerkennung motiviert und zeigt dem Autor, was gut funktioniert. Ein kurzes „// Praise: Die Einleitung erklärt das Problem sehr verständlich. Gut gemacht!“ kann dazu beitragen, dass Ihr Gegenüber offen für kritisches Feedback bleibt.

• Fragen stellen, um Verständnis zu verbessern: Wenn etwas unklar ist, formulieren Sie eine Frage statt einer Feststellung. Zum Beispiel: „// Question: Würden Sie hier eventuell näher erläutern, wie dieses Modul konfiguriert wird?“. Durch Fragen regen Sie eine Erklärung an, ohne vorschnell zu urteilen.

Don’ts – das sollten Sie vermeiden:

• Absolutheitsansprüche und Befehlston: Vermeiden Sie Formulierungen wie „Das muss geändert werden“ oder „Du solltest …​“. Solche Ausdrücke klingen schnell bevormundend oder aggressiv. Besser ist es, die eigene Perspektive zu betonen („Aus meiner Sicht könnte man…“) und Raum für Diskussion zu lassen.

• Persönliche Angriffe oder Schuldzuweisungen: Kommentare dürfen nie gegen die Person selbst gehen, sondern sich immer auf das Dokument beziehen. Unterlassen Sie sarkastische oder abwertende Bemerkungen („Schon wieder falsch gemacht…“). Solche Kommentare haben in einer produktiven, kollaborativen Review nichts verloren. Bleiben Sie immer beim Sachthema: „Diese Formulierung ist missverständlich“ statt „Sie haben das missverständlich geschrieben“.

• Vage Kritik ohne Kontext: Aussagen wie „Das ist schlecht“ helfen niemandem. Wenn Ihnen etwas missfällt, erklären Sie warum und, falls möglich, wie man es verbessern kann. Unbegründete Kritik frustriert nur, während begründetes Feedback einen Lern- und Verbesserungsprozess anstößt.

• „Warum?“ als Vorwurf formulieren: Direktes „Warum hast du…?“ kann defensiv wirken, da es oft nicht als echte Frage, sondern als versteckte Kritik verstanden wird. Fragen Sie stattdessen offen nach Hintergründen: „Was war der Gedanke hinter dieser Struktur?“ – so zeigen Sie echtes Interesse, ohne zu unterstellen, etwas sei falsch.

• Zu viele Kommentare auf einmal: Überfrachten Sie einen Text nicht mit einer Flut von Anmerkungen zu jeder Kleinigkeit. Priorisieren Sie die wichtigen Punkte. Eine endlose Liste an Kommentaren – insbesondere bei Kleinigkeiten – kann den Autor überwältigen und demotivieren. Setzen Sie Schwerpunkte, damit das Feedback verdaulich bleibt.

Indem Sie diese Do’s und Don’ts beherzigen, sorgen Sie für eine wertschätzende Feedback-Kultur. Das Ziel ist, dass Kommentare zu Verbesserungen führen und nicht zu Frust.

Conventional Comments und andere Ansätze für Kommentare

Um Kommentare systematisch hilfreicher zu gestalten, haben sich in der Tech-Branche bestimmte Konventionen etabliert. Eine der bekanntesten Bewegungen ist Conventional Comments. Dieses Format standardisiert, wie Feedback formuliert wird: Jeder Kommentar wird mit einem kurzen Label eingeleitet, das sofort den Ton und Zweck klarmacht.

Solche Labels - etwa praise, nitpick, suggestion, issue oder question - kategorisieren den Kommentar-Typ und machen ihn für alle Beteiligten schneller verständlich. Interessant ist, dass Conventional Comments nicht nur für Code-Reviews gedacht ist, sondern ganz allgemein für jegliche Art von Review-Prozess, von Dokumentenreviews bis hin zu RFC-Diskussionen.

Stellen Sie sich vor, ein Kollege hinterlässt im Dokument den Kommentar:

„issue: Die Beschreibung dieses Features ist unklar.“

Allein durch das vorangestellte issue erkennen Sie sofort: Hier wird auf ein Problem hingewiesen, das behoben werden sollte, statt auf eine bloße Anregung oder Frage. Diese kleine Ergänzung verhindert Missverständnisse und sorgt für effizientere Diskussionen.

Conventional Comments verfolgt damit ein ähnliches Ziel wie die bekannten Conventional Commits bei Git-Commit-Nachrichten, nur eben für Review-Kommentare.

Arten von Kommentaren in Conventional Comments (mit Beispielen):

Diese Labels sind die Kernkategorien von Conventional Comments. Einige Teams erweitern oder variieren die Liste noch, z. B. mit typo für Tippfehler oder polish für kleine Qualitätsverbesserungen ohne akutes Problem.

Wichtig ist nicht, dass jeder Kommentar unbedingt perfekt eingeordnet wird, sondern dass alle Beteiligten ein gemeinsames Verständnis dieser Kategorien haben. So wissen Reviewer wie Autoren sofort, worum es geht: Ein praise erfordert keine Aktion außer sich zu freuen, ein issue hingegen schon. Außerdem wird der Tonfall durch das Label gesetzt. nitpick signalisiert etwa „nur ein kleiner Hinweis“, was Missverständnisse vorbeugt.

Neben Conventional Comments gibt es auch andere Ansätze, die auf ähnliche Ziele abzielen. Manche Teams verwenden zum Beispiel einfache Präfixe wie „Frage:“ oder „Anregung:“ oder markieren die Dringlichkeit durch Zusätze wie „(optional)“ oder „(muss)“. Auch das Konzept blocking/non-blocking ist verbreitet – also kenntlich zu machen, ob ein Kommentar einen zwingenden Änderungsbedarf darstellt oder nur eine optionale Verbesserung ist.

Conventional Comments unterstützt dies explizit durch Dekorationen wie (non-blocking) oder (blocking), die man an ein Label anhängen kann. Ein Beispiel wäre: "issue (non-blocking): …​" für einen Hinweis, der zwar ein Problem beschreibt, dessen Behebung aber nicht Voraussetzung zur Veröffentlichung ist.

Ein weiterer wichtiger Trend ist die Betonung von Empathie und Klarheit in Kommentaren (Stichwort Non-violent Code Review). Unabhängig vom verwendeten Label-System sollten Kommentare inhaltlich immer freundlich und konstruktiv sein. Bewegungen wie die Non-violent Communication angewandt auf Code- und Dokumentenreviews empfehlen z. B., Ich-Botschaften zu verwenden und Urteile zu vermeiden. Das heißt, statt „Das ist falsch geschrieben“ lieber „Mir ist es schwergefallen, diesen Satz zu verstehen“. Solche Ansätze lassen sich hervorragend mit Conventional Comments kombinieren: Das Label gibt den Rahmen vor (z. B. suggestion), und die eigentliche Nachricht bleibt respektvoll und lösungsorientiert.

Exkurs: Konstruktive Kritik – Wie kritisiert man richtig?

Auch mit den besten Kommentar-Konventionen steht und fällt alles mit der Art und Weise, wie Kritik vorgetragen wird. In diesem Exkurs gehen wir darauf ein, wie Sie kritische Anmerkungen so formulieren, dass sie vom Gegenüber nicht als Angriff, sondern als Hilfe zur Verbesserung verstanden werden.

• Sprechen Sie über den Text, nicht über den Autor: Halten Sie Kommentare sachbezogen. Formulieren Sie z. B. „Die Beschreibung des Ablaufs ist an dieser Stelle unklar.“ anstatt „Sie haben das unklar beschrieben.“. Indem Sie persönliche Pronomen wie „Du/Sie“ vermeiden, fühlt sich niemand persönlich angegriffen. Bleiben Sie beim Inhalt – das Problem liegt im Text, nicht an der Person dahinter.

• Wählen Sie den richtigen Ton: Der schriftliche Kanal birgt immer das Risiko von Missverständnissen, da Mimik und Tonfall fehlen. Achten Sie daher bewusst auf einen freundlichen, konstruktiven Ton. Ein kurzer Dank oder ein positiv formuliertes Feedback vorneweg kann Wunder wirken („Danke für die ausführliche Beschreibung der Architektur. Ich hätte einen kleinen Vorschlag…“). Vermeiden Sie unbedingt sarkastische oder spöttische Bemerkungen. Diese haben in produktiven Reviews nichts verloren.

• Kritisieren, aber mit Lösung oder Lernchance: Kritik ist am wirkungsvollsten, wenn Sie sie mit einem Weg zur Verbesserung verknüpfen. Erläutern Sie nicht nur, was nicht stimmt, sondern warum es problematisch ist und wie man es besser machen könnte. Beispiel: „Hier fehlt eine Definition des Fachbegriffs. Das könnte Leser ohne Hintergrundwissen verwirren. Vielleicht können wir einen kurzen Satz zur Erklärung einfügen?“ – So erkennt der Autor das Problem und hat direkt einen Ansatz zur Lösung.

• „Ich habe…“ statt „Man sollte…“: Teilen Sie Ihre Perspektive, ohne sie absolut zu setzen. Aussagen wie „Man versteht das so nicht.“ klingen pauschal. Besser: „Ich habe an dieser Stelle nicht sofort verstanden, wie X funktioniert.“ Damit zeigen Sie, dass es Ihr Eindruck ist, und laden zur Klärung ein, statt allgemein über „richtig“ oder „falsch“ zu urteilen. Diese persönliche Herangehensweise wirkt weniger konfrontativ und öffnet ein Gespräch.

• Fragen stellen und gemeinsam Lösungen finden: Konstruktive Kritik heißt auch, im Dialog zu bleiben. Fragen Sie nach, wenn Ihnen etwas unstimmig vorkommt („Was halten Sie davon, hier ein Diagramm zur Verdeutlichung einzubauen?“), anstatt apodiktisch Änderungen zu verlangen. So geben Sie dem Autor die Chance, seine Sicht zu erklären oder gemeinsam mit Ihnen eine Lösung zu erarbeiten.

• Timing und Umfang bedenken: Überlegen Sie, welche Kritikpunkte wirklich relevant sind. Priorisieren Sie Wesentliches (Inhalt, Verständlichkeit, fachliche Richtigkeit) vor stilistischen Kleinigkeiten, sofern letztere nicht gegen feste Richtlinien verstoßen. Und: Nicht alles muss in einem einzigen Review-Durchgang kommentiert werden. Wenn sehr viele Punkte auffallen, ist es manchmal sinnvoller, ein persönliches Gespräch zu suchen oder die Anmerkungen aufzuteilen, damit der andere nicht „erschlagen“ wird. Konstruktive Kritik zu üben erfordert Empathie und Übung. Denken Sie stets daran, dass auf der anderen Seite ein Mensch Ihre Worte liest. Ziel ist es, Unterstützung statt Bloßstellung zu bieten. Wenn Kritik im richtigen Ton und Kontext kommt, wird sie vom Gegenüber viel eher angenommen – und genau das brauchen wir, um Dokumentation gemeinsam kontinuierlich zu verbessern.

Kommentare in AsciiDoc mit adoc Studio

Nun stellt sich die praktische Frage: Wie setzen Sie all diese Kommentar-Techniken konkret in Ihrer Dokumentation um, insbesondere wenn Sie AsciiDoc als Format nutzen? Glücklicherweise unterstützt AsciiDoc Kommentare direkt und ermöglicht es, die oben genannten Konventionen nahtlos einzubinden.

adoc Studio – ein populärer Editor für AsciiDoc-Dokumente – nutzt diese Syntax ebenfalls nativ, sodass Sie beim Schreiben und Reviewen komfortabel damit arbeiten können.

Inline-Kommentare in AsciiDoc:

Wenn Sie in einer AsciiDoc-Datei eine Zeile mit // beginnen, wird diese komplett als Kommentar behandelt. Alles, was in dieser Zeile nach den beiden Schrägstrichen steht, ignoriert der AsciiDoc-Prozessor. Der Text erscheint also nicht im exportierten Dokument. Sie können auf diese Weise kurze Anmerkungen direkt an einzelne Zeilen hängen. Konventionsgemäß fügt man nach // ein Leerzeichen ein und schreibt dann den Kommentar.

// suggestion: Hier ein Beispielsatz zur Verdeutlichung einfügen.

Inline-Kommentare eignen sich hervorragend, um Conventional-Comments-Labels direkt im Fließtext unterzubringen. Ein // issue: …​ an einer bestimmten Stelle markiert z. B. einen Problempunkt genau dort, wo er auftritt, ohne den Leser der veröffentlichten Doku zu stören.

Block-Kommentare in AsciiDoc:

Für ausführlichere Anmerkungen über mehrere Zeilen oder ganze Abschnitte bietet AsciiDoc Block-Kommentare. Diese beginnen mit einer Zeile //// und enden erst eieder, wenn erneut //// erscheint. Alles dazwischen, mehrere Sätze oder Listen, wird komplett ausgeblendet.

////
issue: Der folgende Abschnitt ist noch unklar formuliert.
Bitte präzisieren. Eventuell ein Diagramm hinzufügen?
////

Sie können Block-Kommentare nutzen, um umfangreiches Feedback oder Diskussionspunkte direkt im Text zu hinterlegen, ohne den Lesefluss im Quelltext durch viele einzelne //-Zeilen zu stören. adoc Studio erkennt diese Block-Kommentare ebenfalls und hebt sie im Editor meist farblich hervor, sodass Sie auf einen Blick sehen, welche Passagen intern auskommentiert sind. Gerade im Team spielt diese native Kommentarfunktion ihre Stärken aus. Jeder Beteiligte sieht im Quellcode sofort alle Anmerkungen der Kollegen, sauber getrennt vom eigentlichen Inhalt.

adoc Studio für Mac, iPad & iPhone

Technische Dokumentation
in AsciiDoc erstellen

14 Tage gratis testen →

Ein praktischer Tipp: Nutzen Sie Kommentare auch, um auf Styleguides oder Entscheidungen zu verweisen. Wenn Ihr Team etwa einen bestimmten Schreibstil vereinbart hat, können Sie im Review-Prozess einen Block-Kommentar einfügen wie:

////
nitpick: Laut Styleguide sollen wir keine Passivformen verwenden.
Könnten Sie diesen Satz aktiv umformulieren?
////

Dabei hilft es, ggf. einen Link zum Styleguide in den Kommentar zu packen. Solche Hinweise verankern Qualitätsstandards direkt im Text und erleichtern es dem Autor, den Grund hinter einer Anmerkung nachzuvollziehen.

Fazit

Kommentare sind mehr als nur „Notizen am Rande“. Richtig eingesetzt, werden sie zum integralen Bestandteil eines professionellen Dokumentations-Workflows. Indem Sie klare Konventionen wie Conventional Comments befolgen, Do’s and Don’ts für den Ton Ihrer Kritik beherzigen und die technischen Möglichkeiten von AsciiDoc/adoc Studio ausschöpfen, stellen Sie sicher, dass Ihr Feedback verstanden und geschätzt wird.

Geschrieben von:

Marvin Blome

Content-Ersteller und Technologie-Enthusiast