Bilder verwenden, ohne den Lesefluss zu brechen

Ein Bild gehört in die Dokumentation, wenn es einen Zustand, Ablauf, Zusammenhang oder ein Ergebnis schneller erklärt als Text. Seine Darstellung folgt dieser Aufgabe. Ein Screenshot, der einen Satz unterstützt, braucht eine andere Behandlung als ein Diagramm, das Leser genau untersuchen müssen.

Ginko Docs rendert normale Markdown-Bilder über Nuxt Image und kann eine Vergrößerung beim Anklicken ergänzen. Die figure-Komponente fügt explizite Abmessungen, eine Caption, Seitenverhältnis und optionalen Bleed hinzu, ohne ein eigenes Vue-Template für die Seite zu verlangen.

Verwende Markdown für Bilder im Lesefluss

Nutze die normale Bildsyntax, wenn der umgebende Absatz den Kontext liefert und das Bild keine Caption benötigt.

Beschreibe im Alt-Text die Information, die ein Leser aus dem Bild braucht. Wiederhole nicht „Bild von“ und verwende nicht den Dateinamen. Trägt ein Bild keine Information, ist ein leerer Alt-Text besser als eine erfundene Beschreibung.

Verwende eine Figure für Caption und stabile Geometrie

Nutze eine Figure, wenn die Caption Bedeutung ergänzt oder explizite Abmessungen einen Layout Shift verhindern sollen.

Die Props width und height beschreiben das Quellbild. Dadurch reserviert der Browser den richtigen Platz, bevor die Datei geladen ist. aspect und fit steuern die Darstellung; sie sollten keinen falsch zugeschnittenen Quell-Asset ausgleichen.

Nutze Bleed nur für wichtige Details

Eine breitere Figure hilft bei dichten Diagrammen, Vergleichs-Screenshots oder redaktionellen Fotos, die innerhalb der Textspalte wichtige Details verlieren.

Verwende Bleed nicht als Dekoration auf jeder Seite. Wiederholte Breitenwechsel unterbrechen das Scannen und lassen gewöhnliche Screenshots wichtiger erscheinen als die Anleitung um sie herum.

Halte Text und Medien synchron

Platziere ein Bild nach dem Satz, der es einführt. Erkläre die Schlussfolgerung zusätzlich im Text; ein Screenshot darf nicht der einzige Ort für einen erforderlichen Wert oder eine Fehlermeldung sein. Aktualisiere Screenshots, wenn sich Labels, Routen oder Standardwerte ändern.

Bei vergrößerbaren Bildern muss die verkleinerte Ansicht das Hauptmotiv erkennen lassen und der Original-Asset scharf genug für Details sein. Ein unscharfer Screenshot wird in einem Dialog nicht hilfreicher.

Der endgültige Asset braucht einen stabilen öffentlichen Pfad, aussagekräftigen Alt-Text, bei figure intrinsische Abmessungen und nur dann eine Caption, wenn sie Information ergänzt, die der Absatz noch nicht enthält.