Ein Software-Dokumentationsset mit Screenshots planen

Ein Dokumentationsset mit Screenshots ist leicht begonnen und schwer zu pflegen. Jedes Bild ist eine Kopie der Oberfläche an einem bestimmten Tag, und die Oberfläche ändert sich weiter. Die Planung vor der Aufnahme entscheidet, ob das Set die erste Überarbeitung der Oberfläche übersteht.

Dieser Beitrag beschreibt, wie Sie das Set strukturieren, Regeln für Screenshots festlegen und die Bilder mit Temposhot auf einem Mac erstellen. Ein durchgehendes Beispiel begleitet jeden Abschnitt: eine kleine Rechnungs-Webanwendung mit fünf Produktbereichen und einer Person für technische Dokumentation, die auch den Support übernimmt.

Die Fragen der Leser auflisten

Sammeln Sie echte Fragen, bevor Sie Seiten festlegen. Gute Quellen sind Support-Tickets, Verkaufsgespräche, Onboarding-Sitzungen, interne Chat-Verläufe und Suchbegriffe in der bestehenden Dokumentation.

Schreiben Sie jede Frage in den Worten der Leser:

• „Wie lade ich ein Teammitglied ein?“
• „Warum ist mein Export leer?“
• „Was bedeutet der Sync status?“
• „Welcher Tarif enthält Audit-Logs?“

Fassen Sie Dubletten zusammen. Die resultierende Liste bestimmt den Umfang des Sets. Alles, was nicht auf der Liste steht, kann warten.

Beispiel: von Tickets zur Fragenliste

Das Rechnungsteam exportierte 240 Support-Tickets aus den letzten 90 Tagen. Das Lesen nur der Betreffzeilen und der ersten Kundennachricht dauerte etwa zwei Stunden. Nach dem Zusammenführen der Dubletten blieben 52 verschiedene Fragen übrig.

Neun Fragen kamen jeweils mehr als zehnmal vor. Diese neun deckten fast die Hälfte aller Tickets ab und legten daher die Reihenfolge der Arbeit fest. Die übrigen 43 Fragen kamen in ein nach Bereichen sortiertes Backlog: Rechnungen, Kunden, Zahlungen, Einstellungen und Abrechnung.

Die Wortwahl der Leser festhalten

Halten Sie die Formulierung der Leser neben jeder Frage fest, auch wenn sie nicht zum Oberflächenlabel passt. Ein Kunde, der „remove a card“ schreibt, sucht nicht nach „Payment methods“. Der Seitentitel verwendet das Produktlabel. Der erste Satz kann den Begriff der Leser wiederholen, damit die Suche beide Begriffe findet.

Notieren Sie außerdem den Kontext jeder Frage: Tarif, Rolle und Gerät. Die Frage „How do I refund an invoice“ von einem Kontoinhaber und dieselbe Frage von einer Person mit der Rolle Viewer führen zu unterschiedlichen Seiten. Die erste ist eine Aufgabenanleitung, die zweite eine Fehlerseite zu fehlenden Berechtigungen.

Fragen entfernen, die die Dokumentation nicht lösen kann

Manche Tickets beschreiben einen Fehler oder eine fehlende Funktion. Eine Seite, die einen Fehler erklärt, wird zu einer Umgehung, die den Fix überdauert. Im Beispiel wurden 6 Fehlermeldungen beim Zusammenführen aussortiert, bevor die Zahl 52 feststand. Sie gingen an das Produktteam und nicht in das Dokumentations-Backlog.

Andere Fragen entstehen durch ein unklares Label. Wenn zehn Leser fragen, was „Sync“ bedeutet, hilft eine Referenzseite, ein klareres Label hilft jedoch mehr. Leiten Sie auch diese Fragen an das Produktteam weiter und schreiben Sie die Seite nur, wenn das Label bestehen bleibt.

Jeder Frage einen Seitentyp zuordnen

Unterschiedliche Fragen brauchen unterschiedliche Seitenformen. Wenn man sie vermischt, werden Seiten lang und schwer zu überfliegen.

Seitentyp	Beantwortet	Screenshots
Aufgabenanleitung	„Wie mache ich X“	Einen pro Schritt
Referenz	„Was bedeutet X“	Eine annotierte Übersicht pro Bildschirm
Fehlerbehebung	„Warum ist X fehlgeschlagen“	Der Fehlerzustand und die Lösung
Konzept	„Wie funktioniert X“	Diagramme, wenige oder keine Screenshots

Versehen Sie jede Frage der Liste mit einem Typ. Die meisten Produktfragen werden zu Aufgabenanleitungen.

Screenshots vor dem Schreiben zählen

Der Seitentyp bestimmt, wie viele Bilder eine Seite enthält. Multiplizieren Sie diesen Wert mit der Anzahl der Seiten. Das Ergebnis ist die Zahl der Bilder, die nach jeder Überarbeitung aktualisiert werden müssen. Diese Zahl sollte bekannt sein, bevor jemand ein Aufnahmewerkzeug öffnet.

Im Beispiel wurden 31 der 52 Fragen zu Aufgabenanleitungen mit durchschnittlich 7 Schritten. Zwölf wurden zu Fehlerseiten mit je 2 Bildern, 6 zu Referenzseiten mit je einer annotierten Übersicht und 3 zu Konzeptseiten ohne Screenshots.

Die 247 Bilder bilden die eigentliche Pflegelast des Sets. Eine Überarbeitung eines Produktbereichs, die ein Fünftel davon betrifft, bedeutet etwa 50 Ersetzungen und ein bis zwei Arbeitstage. Wer diese Zahl kennt, kann die folgende Screenshot-Richtlinie leichter begründen.

Fragen mit mehreren Typen aufteilen

Manche Fragen verbinden zwei Typen. „Why is my export blank and how do I fix it“ ist eine Fehlerseite, die auf eine Aufgabenanleitung verweist. Schreiben Sie die Fehlerseite mit dem Fehler und der Ursache und verlinken Sie für den vollständigen Ablauf auf die Aufgabenanleitung.

Eine Screenshot-Richtlinie festlegen

Legen Sie einmal fest, wie Screenshots aussehen, und halten Sie es schriftlich fest. Ein einheitliches Set wirkt gepflegt und lässt sich schneller aktualisieren.

• Fenstergröße: eine feste Größe für alle Aufnahmen. Das Ziel Specific Window in Action Capture behält dasselbe Fenster für einen gesamten Durchlauf bei.
• Design und Sprache: hell oder dunkel und eine Oberflächensprache.
• Daten: nur Beispielkonten und Platzhalternamen.
• Zuschnitt: das Fenster oder das Panel, nie der gesamte Desktop. Verwenden Sie Framing mit Focus on action auf Balanced oder Close.
• Markierungen: ein Klickmarker oder ein Pfeil pro Bild, eine Akzentfarbe.
• Format: PNG für Oberflächentext, WebP, wenn Ihre Website kleinere Dateien braucht.

Legen Sie außerdem fest, wo keine Screenshots nötig sind: bei einer Einstellung mit einem einzigen Feld, bei einem Schritt, dessen Label im Text steht, und bei einem Bildschirm, der sich mit jedem Release ändert.

Die Richtlinie in Aufnahmeeinstellungen übertragen

Eine schriftliche Richtlinie hilft nur, wenn die Aufnahmeeinstellungen zu ihr passen. Konfigurieren Sie Action Capture einmal, dann werden die Werte auf dem Mac für jeden späteren Durchlauf gespeichert. Das Beispielteam verwendete die folgenden Einstellungen für alle 31 Aufgabenanleitungen.

Specific Window legt ein Browserfenster als Ziel für den gesamten Durchlauf fest, daher haben alle Schritte dieselbe Breite in Pixeln. Schalten Sie Include toolbar in captures aus, sonst erscheint die schwebende Symbolleiste in den Dokumentationsbildern. Lassen Sie Capture outside clicks ausgeschaltet, außer die Aufgabe verwendet ein zweites Fenster, etwa einen Passwort-Manager.

Framing-Stufen je Seitentyp festlegen

Framing verändert das Ausgangsbild nicht. Die Richtlinie kann daher eine Stufe festlegen und trotzdem Ausnahmen zulassen. Aufgabenanleitungen verwenden standardmäßig Balanced (Stufe 3). Dieser Zuschnitt zeigt genug von der Seite, damit Leser das Bedienelement finden. Kleine Bedienelemente wie ein Schalter in einer langen Einstellungsliste wechseln zu Close (Stufe 4).

Referenzübersichten verwenden kein Framing. Sie zeigen das gesamte Fenster mit nummerierten Beschriftungen, weil jeder Bereich benannt werden soll. Step Numbers ist ein Pro-Werkzeug. Im kostenlosen Tarif erreichen Sie dasselbe Ergebnis mit manuell platzierten Text-Beschriftungen.

Festlegen, wann nicht aufgenommen wird

Jedes Bild ist eine künftige Aktualisierung. Die Richtlinie sollte daher auch Fälle nennen, in denen kein Screenshot entsteht. Das Beispielteam ließ Bilder für Schritte weg, in denen die einzige Aktion die Eingabe eines Werts in ein beschriftetes Feld war. Außerdem ließ es Bestätigungsmeldungen weg, die nach 3 Sekunden verschwinden, und beschrieb die Meldung stattdessen im Text.

Wenn keiner der fünf Punkte zutrifft, beschreiben Sie den Schritt nur im Text. Im Beispiel entfielen durch diese Regel 38 der 217 geplanten Bilder für Aufgabenanleitungen, bevor die Aufnahme begann.

Für jede Aufnahme ein Beispielkonto vorbereiten

Screenshots aus verschiedenen Konten zeigen unterschiedliche Namen, Summen und Daten, und Leser bemerken das. Das Beispielteam legte einen Beispiel-Arbeitsbereich mit 3 Kunden, 12 Rechnungen und 2 Zahlungsmethoden an, alle mit Platzhalternamen. Jede Anleitung beginnt in diesem Arbeitsbereich, daher erscheint auf jeder Seite derselbe Kundenname.

Setzen Sie die Beispieldaten vor jedem Durchlauf zurück. Eine Anleitung, die aufgenommen wird, nachdem eine andere Anleitung eine Rechnung gelöscht hat, zeigt 11 statt 12 Rechnungen, und die nächste Aktualisierung passt nicht mehr. Schreiben Sie die Rücksetzschritte an den Anfang des Richtliniendokuments, damit eine andere Person sie wiederholen kann.

Stellen Sie das Browserfenster vor jedem Durchlauf auf eine Größe ein und belassen Sie es dabei. Temposhot nimmt das Fenster in seiner aktuellen Größe auf und ändert die Fenstergröße nicht. Ein Hinweis in der Richtlinie, etwa „browser window at 1440 points wide, zoom 100 percent“, hält Aufnahmen von verschiedenen Tagen im gleichen Maßstab.

Bilder für den Austausch benennen und ablegen

Jedes Bild wird irgendwann ersetzt. Benennen Sie Dateien so, dass Sie alle Bilder eines Bildschirms schnell finden.

Ein Muster wie area-task-step.png, zum Beispiel billing-change-plan-03.png, sortiert nach Bereich und Aufgabe. Legen Sie pro Anleitung einen Ordner an und speichern Sie das Temposhot-Document jeder Anleitung, damit Sie nach Änderungen erneut exportieren können.

Die Bildexporte von Temposhot verwenden Seitentitel in den Dateinamen. Legen Sie die Titel vor dem Export fest oder benennen Sie die Dateien danach in Ihrem Dokumentations-Repository um. Das ZIP-Paket legt document.json neben den gerenderten PNG-Seiten ab. Das hilft, wenn Sie den Import in ein Dokumentationssystem per Skript ausführen.

Ordnerstruktur für das Beispielset

Ein Ordner pro Produktbereich enthält einen Ordner pro Anleitung. Die exportierten Bilder liegen neben der Seite, die sie verwendet. Ein Pull Request, der eine Anleitung ändert, zeigt dadurch auch, welche Bilder sich geändert haben.

Seitentitel und Dateinamen synchron halten

Da Temposhot Bilddateien nach den Seitentiteln benennt, ergibt ein Titel wie Click "Change plan" einen Dateinamen, der sich schlecht sortieren lässt. Es gibt zwei brauchbare Wege. Sie schreiben die Seitentitel in den endgültigen Text für Leser um und benennen die Dateien im Repository per Skript um. Oder Sie exportieren ein ZIP-Paket und verwenden die Seitenreihenfolge in document.json für die Dateinamen.

Welchen Weg das Team auch wählt, die Schrittnummer im Dateinamen sollte zur Schrittnummer auf der Seite passen. Wird Schritt 4 gelöscht, nummerieren Sie die folgenden Dateien im selben Commit neu.

Die Quell-Documents speichern

Jedes exportierte Bild stammt aus einem Document auf dem Mac, auf dem es aufgenommen wurde. Documents liegen auf diesem Mac in der Documents-Bibliothek (Command+4). Temposhot synchronisiert sie nicht. Benennen Sie jedes Document genauso wie den Anleitungsordner, zum Beispiel billing-change-plan, damit sich die Quelle jedes Bildes über die Suche in der Bibliothek finden lässt.

Aufgabenanleitungen vor allgemeinen Rundgängen erstellen

Aufgabenanleitungen beantworten die häufigsten Fragen und lassen sich am einfachsten prüfen. Schreiben Sie sie zuerst.

1. Action Capture öffnen

   Drücken Sie Command+3, wählen Sie Start Action Capture und wählen Sie Specific Window.

2. Aufgabe ausführen

   Führen Sie die Aufgabe einmal durch. Jeder akzeptierte Klick speichert das Fenster kurz vor dem Klick, mit einem Entwurfstitel aus Parse clicked elements.

3. Beenden und bearbeiten

   Wählen Sie Finish capture. Im Editor schreiben Sie die Titel um, legen das Framing der Seiten fest und fügen Markierungen hinzu.

4. Seiten exportieren

   Öffnen Sie More export formats und wählen Sie PNG- oder WebP-Seiten für die Dokumentationswebsite.

Produktrundgänge und Übersichtsseiten kommen später, wenn die Aufgabenanleitungen zeigen, welche Bildschirme am wichtigsten sind. Der Action-Capture-Leitfaden und der Leitfaden zum Export von Documents beschreiben die Details.

Die erste Serie nach Ticketaufkommen sortieren

Das Beispielteam nahm in der ersten Woche die neun am häufigsten gestellten Fragen auf. Jede Anleitung dauerte etwa 25 Minuten: 5 Minuten zum Zurücksetzen des Beispielkontos, 5 Minuten zum Aufnehmen und 15 Minuten zum Bearbeiten von Titeln, Framing und Markierungen. Neun Anleitungen brauchten insgesamt etwa vier Stunden.

Entwurfstitel in Anleitungen umschreiben

Parse clicked elements füllt jeden Seitentitel mit dem Namen des Bedienelements, zum Beispiel Click "Change plan". Klicks auf Bedienelemente ohne lesbaren Namen erhalten Click here. Beides sind Entwürfe. Ein Titel für Leser beginnt mit einem Verb, nennt das Bedienelement in Fettschrift und ergänzt das Ergebnis, wenn es nicht offensichtlich ist.

Entwurfstitel	Umgeschriebener Titel
Click "Billing"	Billing in der Seitenleiste öffnen
Click here	Die Tarifkarte für Team auswählen
Click "Confirm"	Confirm auswählen, um den Tarif zur nächsten Verlängerung zu wechseln

Der umgeschriebene Titel wird beim Export auch zum Bilddateinamen. Ein klarer Titel hilft daher Lesern und dem Repository gleichermaßen.

Die Schrittanzahl mit dem Limit des kostenlosen Tarifs prüfen

Der kostenlose Tarif pausiert einen Action-Capture-Durchlauf nach 5 Schritten. Bereits aufgenommene Schritte bleiben gespeichert. Anleitungen mit 7 Schritten wie im Beispiel brauchen Temposhot Pro oder zwei Durchläufe in einem Document. Einen zweiten Durchlauf starten Sie über Capture new images… im Pages-Panel. Dabei werden die neuen Frames an das geöffnete Document angehängt.

Seiten mit Tastenkürzeln bearbeiten

Das Bearbeiten nimmt den größten Teil der 25 Minuten pro Anleitung ein. Die folgenden Editor-Tasten decken die häufigsten Änderungen an Dokumentationsseiten ab.

Annotationen verändern das Bild nicht dauerhaft. Ein in diesem Release hinzugefügtes Rechteck lässt sich nach der nächsten Überarbeitung verschieben oder löschen, ohne den Schritt erneut aufzunehmen, solange der zugrunde liegende Bildschirm noch übereinstimmt.

Das Dokumentationsset verknüpfen

Leser landen selten auf der Seite, die sie brauchen. Verknüpfen Sie Seiten, damit Leser vom Konzept zur Aufgabe und vom Fehler zur Lösung wechseln können.

• Jede Aufgabenanleitung verlinkt auf ihre Voraussetzungen und auf die nächste wahrscheinliche Aufgabe.
• Jede Fehlerseite verlinkt auf die Aufgabenanleitung, die den Fehler behebt.
• Jede Referenzseite verlinkt auf die Aufgaben, die den Bildschirm verwenden.

Eine kurze Übersichtsseite pro Produktbereich, die Aufgaben nach Ziel auflistet, hilft Lesern, die stöbern statt suchen.

Verlinkungsmuster am Beispiel einer Frage

Die Frage „Why is my export blank“ erzeugte im Beispiel eine Kette aus vier Seiten. Ein Leser, der auf einer dieser Seiten landet, erreicht die anderen drei mit einem Klick.

Verwaiste Seiten vermeiden

Listen Sie nach der Veröffentlichung jede Seite auf und zählen Sie die eingehenden Links. Eine Seite ohne eingehenden Link ist nur über die Suche erreichbar. Im Beispiel hatten 4 der 52 Seiten keinen eingehenden Link. Jede davon wurde ihrer Bereichsübersicht hinzugefügt.

Verantwortlichkeiten und Review-Auslöser festlegen

Weisen Sie jeder Seite eine verantwortliche Person zu, in der Regel das Team, das die Funktion verantwortet. Halten Sie die Produktversion fest, zu der die Screenshots passen.

Review-Auslöser funktionieren besser als reine Kalendererinnerungen:

• Ein Release ändert einen Bildschirm, der im Set gezeigt wird.
• Ein Label oder ein Menüpunkt wird umbenannt.
• Der Support meldet einen Schritt, der nicht mehr passt.
• Ein fester Zeitraum, etwa ein Quartal, vergeht ohne anderen Auslöser.

Der Beitrag Screenshot-Dokumentation aktuell halten beschreibt den Aktualisierungsablauf.

Bilder nach einem Release ersetzen

Wenn ein Release einen Bildschirm ändert, machen die Dateinamen die betroffenen Bilder leicht auffindbar. Suchen Sie im Repository nach dem Bereichspräfix, öffnen Sie die passenden Documents und führen Sie nur die geänderten Schritte erneut aus.

Neue Seiten aus einer Aufnahme lassen sich nach der ausgewählten Seite einfügen. Wählen Sie die Seite vor dem geänderten Schritt aus und starten Sie die Aufnahme. Die neue Seite landet an der richtigen Position.

Verantwortung nach Produktbereich aufteilen

Eine einzelne Person kann nach jedem Release nicht 52 Seiten prüfen. Das Beispielteam wies jeden Bereich der zuständigen Person im Engineering zu, die ihn verantwortet. Die Dokumentation übernimmt die Redaktion. Die verantwortliche Person kennzeichnet geänderte Bildschirme im Release-Ticket, und die Dokumentation ersetzt die Bilder.

Die Produktversion auf jeder Seite festhalten

Tragen Sie die Produktversion in die Seitenmetadaten oder in die letzte Zeile der Seite ein, etwa „Screenshots match version 4.2“. Meldet der Support eine Abweichung, zeigt die Version der verantwortlichen Person, wie weit die Seite zurückliegt. Seiten, die mehr als zwei Releases zurückliegen, rücken an die Spitze der Review-Warteschlange.

Häufig gestellte Fragen

Wie viele Screenshots sollte eine Software-Dokumentationsseite haben?

Einen pro Schritt bei Aufgabenanleitungen und so wenige wie möglich in anderen Seitentypen. Jedes Bild ist eine künftige Aktualisierung. Fügen Sie eines nur hinzu, wenn es dem Leser Aufwand erspart.

Sollten Dokumentations-Screenshots den gesamten Bildschirm zeigen?

Selten. Schneiden Sie auf das Fenster oder das Panel zu. Vollbildaufnahmen zeigen fremde Apps und verkleinern den Oberflächentext.

Was ist visuelle Dokumentation?

Dokumentation, die Screenshots, Diagramme oder Videos neben dem Text verwendet. Siehe visuelle Dokumentation im Glossar.

Welches Bildformat sollte eine Dokumentationswebsite verwenden?

PNG-Seiten halten den Oberflächentext scharf. WebP-Seiten ergeben kleinere Dateien und erscheinen unter More export formats nur, wenn auf dem Mac ein WebP-Encoder verfügbar ist. Das Image Compressor kann PNG-Dateien vor dem Hochladen weiter verkleinern.

Wie lange dauert eine Screenshot-Aktualisierung nach einer Überarbeitung?

Das hängt davon ab, wie viele Bilder die geänderten Bildschirme zeigen. Im Beispiel betraf die Überarbeitung eines Bereichs etwa 50 von 247 Bildern. Das erneute Ausführen nur der geänderten Schritte aus den gespeicherten Documents dauerte einen bis zwei Tage. Die Anleitungen von Grund auf neu zu erstellen, hätte etwa eine Woche gedauert.

Können mehrere Personen ein Temposhot-Document gemeinsam nutzen?

Nein. Documents werden auf dem Mac gespeichert, der sie erstellt hat. Teilen Sie die exportierten Dateien über das Dokumentations-Repository und bewahren Sie das Quell-Document jeder Anleitung auf dem Mac der verantwortlichen Person auf.

Ihre Klicks in eine klare Schritt-für-Schritt-Anleitung verwandeln

Action Capture zeichnet jede Aufgabenanleitung in einem Durchgang mit einheitlicher Fenstergröße und Entwurfstiteln auf. Temposhot herunterladen und mit der meistgestellten Frage Ihrer Liste beginnen.