Schlechter Rat: Wie schreibe ich technische Dokumentation? Teil zwei

Tipps zum kompetenten Verfassen technischer Dokumentationen für Benutzer.
Teil 2

Fortsetzung des Handbuchs unseres technischen Redakteurs Andrei Starovoitov, das Ihre Benutzerdokumentation einfacher und verständlicher macht.

Sie können den Anfang des Artikels hier lesen, aber wir haben den Prozess der Dokumentation und Lokalisierung unserer Produkte weiter oben in diesem Artikel beschrieben .

In diesem Teil werden wir die Themen, die hauptsächlich aus Benutzerdokumentation bestehen (insbesondere das Benutzerhandbuch), detailliert analysieren, nämlich Aufgabenthemen , die beschreiben, wie ein bestimmtes Problem gelöst werden kann.



Wie viele Aufgaben sind im Thema zu beschreiben - eine oder mehrere?

Ein Aufgabenthema kann sowohl eine Aufgabe - "Starten einer Windows-Anwendung" ("Starten einer Windows-Anwendung") - als auch mehrere verwandte Aufgaben beschreiben. Das Thema "Leistung optimieren" kann beispielsweise aus den folgenden Abschnitten bestehen: "Speicherplatz automatisch sparen" und "Optimieren Sie Ihr MacBook, um eine bessere Leistung zu erzielen oder Batterie zu sparen" ("Optimieren Sie Ihre Leistung") MacBook für längere Akkulaufzeit oder höhere Leistung “).

Wir sollten versuchen, Aufgabenthemen nach dem Prinzip zu schreiben: ein Thema - eine Aufgabe. Es stimmt, es gibt eine Ausnahme: Wenn Sie zwei Aufgaben haben, die in Aktion entgegengesetzt sind, sollten sie in einem Thema beschrieben werden. Wenn Sie beispielsweise beschreiben müssen, wie Sie die virtuelle Maschine in den Vollbildmodus schalten und später beenden, müssen Sie dies im selben Thema tun.
Wenn Sie mehrere verwandte Aufgaben beschreiben müssen, kann dies auch in einem Thema erfolgen, sofern deren Beschreibung nicht lang ist.

Abschnitte von Aufgabenthemen

Aufgabenthemen bestehen aus:

• Überschrift
• Einführender Teil (auf Englisch „Intro“)
• Sätze, die zu einer Beschreibung dessen führen, was genau der Benutzer tun muss (auf Englisch „Schrittüberschrift“)
• Nummeriert oder ab einem großen Punkt beginnend (auf Englisch „nummerierte oder mit Aufzählungszeichen versehene Schritte“)
• Der letzte Teil (auf Englisch "outro")

Manchmal enthält das Aufgabenthema nicht alle oben genannten Abschnitte. Beispielsweise muss kein Intro oder Outro eingefügt werden. Weiter werden wir auf jeden Abschnitt des Themas näher eingehen.

Überschrift

Wir müssen versuchen, solche Überschriften zu erstellen, damit der Benutzer sofort versteht, was in dem Thema geschrieben wird.

Machen Sie Schlagzeilen groß, aber nicht zu lang zugleich. Lange Header werden in einigen Browsern oder im Apple Help Viewer möglicherweise nicht vollständig angezeigt.

Verwenden Sie beim Schreiben einer Überschrift den Imperativ ("Do this")

Zum Beispiel "Einrichten eines Druckers mit Bonjour".

Verwenden Sie den Imperativ nicht in den Namen von Themen, die nicht beschreiben, wie ein Problem gelöst werden kann.

Verwenden Sie benutzerfreundliche Wörter im Themennamen, konzentrieren Sie sich nicht auf die Elemente der Benutzeroberfläche.

Der Benutzer möchte die Funktionen, Begriffe, Oberflächenelemente usw. nicht verstehen - er muss sein spezifisches Problem lösen. Versuchen Sie daher im Namen des Themas, die Wörter zu verwenden, die der Benutzer selbst verwenden würde. Wenn Sie beispielsweise das Thema "Einrichten Ihres Mac für die Verwendung von Windows-Anwendungen" aufrufen, ist dies für den Benutzer viel verständlicher als das Thema "Informationen zu virtuellen Maschinen".

Versuchen Sie, das Ziel so zu formulieren, wie es der Benutzer wahrscheinlich tun würde. Benennen Sie beispielsweise anstelle von "Remote-Sitzung starten" das Thema "Windows fernsteuern".

Wenn Sie technisch komplexe Begriffe oder Schnittstellennamen verwenden müssen, ist es besser, dies nicht in der Kopfzeile, sondern im einleitenden Teil des Themas zu tun.

Wenn Sie eine Dokumentation in englischer Sprache verfassen, sollten die Wörter im Titel mit einem Großbuchstaben beginnen

Rechts : Richten Sie Ihren Mac für die Verwendung von Windows-Anwendungen ein

Falsch : Richten Sie Ihren Mac für die Verwendung von Windows-Anwendungen ein

(Wir werden die Großschreibung der Überschrift im nächsten Teil des Handbuchs genauer erörtern.)

Intro (Intro)

Im Einführungsteil, der unmittelbar nach der Überschrift steht, sollten Sie schreiben, was der Benutzer wissen muss, bevor er mit der Ausführung der Aufgabe beginnt.

Der Prolog kann enthalten:

• Zusätzliche allgemeine Informationen: Was der Benutzer tun kann.
• Motivation : Warum muss der Benutzer möglicherweise die eine oder andere Aktion ausführen? Im Folgenden finden Sie einen einführenden Beispielteil, in dem beschrieben wird, warum Sie möglicherweise vorgefertigte virtuelle Maschinen herunterladen und verwenden müssen:

Verwenden Sie handelsübliche virtuelle Maschinen

Wenn Sie keine Zeit haben, eine neue virtuelle Maschine mit der erforderlichen Konfiguration zu erstellen, können Sie die fertige virtuelle Maschine mit einer vorkonfigurierten Konfiguration herunterladen.

• Warnungen vor möglichen Schäden an Hardware, Software oder Datenverlust, die auftreten können, während der Benutzer eine Aktion ausführt.
• Wichtige Informationen zu potenziellen Problemen oder Schwierigkeiten, die zwar nicht zu Gesundheitsschäden, Geräten oder Datenverlust führen, jedoch während der Ausführung einer Aufgabe auftreten können.
• Erläuterung: Was bedeutet dieser oder jener Begriff oder wie funktioniert eine Funktion?

Wenn ein Parallels Desktop-Benutzer beispielsweise gleichzeitig mit macOS und Windows arbeiten möchte, als wäre es ein Betriebssystem, können Sie im Einführungsteil über den „Kohärenzmodus“ sprechen, um den Benutzer auf diese Begriffe vorzubereiten wird im Thema weiter verwendet.

• Informationen zu zusätzlichen Bedingungen : In dem Thema, in dem beispielsweise beschrieben wird, wie der Drucker über Bonjour angeschlossen wird, informiert Sie das Intro möglicherweise darüber, welche Windows-Versionen Bonjour unterstützen.
• Für die aktuelle Aufgabe erforderliche Bedingungen : Wenn der Benutzer vor Beginn der Ausführung der im Thema beschriebenen Aufgaben etwas anderes tun oder überprüfen muss, sollte dies im einleitenden Teil erwähnt werden. Und es wäre schön, Links zu Themen zu geben, in denen es beschrieben wird, damit der Benutzer es schnell finden und lesen kann.

Fügen Sie den Prolog nicht dort ein, wo er nicht benötigt wird.

Obwohl der Einführungsteil zusätzliche nützliche Informationen enthält, ist manchmal alles aus dem Titel selbst ersichtlich. In solchen Fällen müssen Sie keinen Einführungstext erstellen, wenn dies nur der Fall wäre.

Zum Beispiel:

Starten Sie Mac-Apps über das Startmenü

Öffnen Sie das Windows-Startmenü und führen Sie einen der folgenden Schritte aus:

• Klicken Sie auf Alle Programme> Parallels Shared Applications und wählen Sie die gewünschte Anwendung aus.
• Geben Sie den Namen der Anwendung in das Suchfeld ein und wählen Sie die gewünschte Anwendung aus den vorgeschlagenen Optionen aus.

Machen Sie den Prolog nicht zu lang

Die Einführung nervt den Benutzer zu lange. In solchen Fällen überspringen Benutzer dies häufig und gehen direkt zur Liste der spezifischen Schritte.

Wenn der Einführungsteil zu groß ist, müssen Sie den Hauptteil erwähnen und einen Link zu einer separaten konzeptionellen Seite oder Referenzseite geben, auf der bereits alles ausführlich beschrieben wird.

Manchmal können Aufzählungszeichen verwendet werden, um das Lesen von Langtext im einleitenden Teil visuell zu erleichtern. Zum Beispiel:



Sagen Sie in der Einleitung nicht, wie Sie die Aufgabe erledigen sollen

Der Prolog ist nicht dafür. Was, wo und wie getan werden muss - muss erst später nach dem einleitenden Teil beschrieben werden.

In seltenen Fällen müssen Sie den Benutzern jedoch möglicherweise mitteilen, was sie zum Ausführen der Aufgabe benötigen. Im folgenden Beispiel erfahren die Benutzer im Einführungsteil, was sie benötigen, um die im Thema beschriebene Aufgabe auszuführen.



Beschreiben Sie die Ergebnisse der Aufgabe nicht im einleitenden Teil.

Dies sollte im letzten Teil ( Outro ) erfolgen.

Der Satz vor den Anweisungen (Schritt Überschrift)

Nach der Einführung müssen Sie eine „einleitende“ Phrase (auf Englisch - „Schrittüberschrift“) einfügen, die den Benutzer zu Anweisungen führt: Was genau muss getan werden, um das eine oder andere Ergebnis zu erzielen?

In Intro schreiben wir beispielsweise: „ Wenn Sie eine Installationsdiskette und einen Aktivierungsschlüssel haben, können Sie damit Windows in einer virtuellen Maschine installieren. ""

Nach dem Intro folgt die Überschrift: " So installieren Sie Windows: "

Und dann die Schritte selbst:

1) Klicken Sie hier.
2) Wählen Sie dies.
3) Und so weiter ...

Bitte beachten Sie: Wenn das Thema kein Intro enthält, ist die Schrittüberschrift optional.

Wenn das Thema aufeinanderfolgende Schritte beschreibt, sollte die Schrittüberschrift wie folgt aussehen: „ Etwas tun:“ („X ausführen:“).
Zum Beispiel: "So wechseln Sie in den Vollbildmodus :" ("So starten Sie Windows:") oder " So wechseln Sie in den Vollbildmodus:" .

Vergessen Sie nicht, am Ende einen Doppelpunkt zu setzen

Wenn die Überschrift benutzerfreundliche Wörter verwendet und Sie komplexe Fachbegriffe oder die Namen der Schnittstellenelemente in der Anleitung verwenden müssen, können Sie Folgendes tun: Im einleitenden Teil erklären Sie, was der Begriff bedeutet, und in der Schrittüberschrift verwenden Sie ihn bereits aktiv.

Zum Beispiel:

1) Wir machen den Header für den Benutzer klarer:

" Windows so einstellen, dass es den gesamten Bildschirm einnimmt"

2) Als nächstes führen wir im Intro den Begriff "Vollbildmodus" ein.

3) Danach können Sie in der Schrittüberschrift den Begriff bereits verwenden, ohne befürchten zu müssen, dass er für den Benutzer nicht verständlich ist:

" So geben Sie den Vollbildmodus ein:" ("So rufen Sie den Vollbildmodus auf:")

Wenn es sich bei den im Thema beschriebenen Schritten nicht um eine Abfolge von Aktionen handelt, sondern um mehrere Möglichkeiten zum Erreichen des Ziels, sollte die Schrittüberschrift wie folgt ausgeführt werden: „Hier sind einige Möglichkeiten, etwas zu tun:“ („Hier sind einige Möglichkeiten, X zu tun:“) oder „ Führen Sie dazu einen der folgenden Schritte aus: ” (“ Um X auszuführen, führen Sie einen der folgenden Schritte aus: ”).

Beispiel: "Hier sind Möglichkeiten zum Herunterfahren von Windows:") oder " Führen Sie einen der folgenden Schritte aus, um einen Drucker anzuschließen : " ("Führen Sie einen der folgenden Schritte aus, um einen Drucker anzuschließen: ”).

Beim Erstellen einer Schrittüberschrift müssen Sie die Wörter verwenden, die die im Aufgabenthema beschriebene Aufgabe widerspiegeln. Hier einige Beispiele auf Englisch:

Seitentitel : Installieren Sie Windows von einer Installations-CD.
Aufgabenabdeckungen : Installieren von Windows mithilfe einer Installations-CD.
Schrittüberschrift : So installieren Sie Windows.

Seitentitel : Passen Sie die Kohärenzeinstellungen an.
Aufgabenabdeckungen : Anpassen, wie Windows im Kohärenzmodus angezeigt wird und sich verhält.
Schrittüberschrift: Zum Anpassen des Kohärenzmodus.

Seitentitel : Stellen Sie Windows so ein, dass es den gesamten Bildschirm einnimmt
Aufgabenabdeckungen : Aufrufen des Vollbildmodus.
Schrittüberschrift : Führen Sie einen der folgenden Schritte aus, um den Vollbildmodus aufzurufen :

Nummerierte Schritte

Alle Themen, die beschreiben, wie eine bestimmte Aufgabe ausgeführt wird, enthalten Anweisungen, was zu tun ist. Diese Aktionen im Text werden normalerweise entweder nummeriert (wenn es sich um eine Reihe aufeinanderfolgender Schritte handelt) oder durch Aufzählungszeichen hervorgehoben (wenn vorgeschlagen wird, nach eigenem Ermessen eine der Listen auszuwählen).

Halten Sie die Liste der erforderlichen Schritte so kurz wie möglich.

Wählen und beschreiben Sie den einfachsten und schnellsten Weg, um eine Aktion abzuschließen. Alternative Methoden können im letzten Teil (Outro) oder in einem anderen Aufgabenthema beschrieben werden. Zwingen Sie den Benutzer nicht, die Anweisungen in 4 Schritten zu lesen, wenn dies durch Klicken auf eine Schaltfläche möglich ist.

Wenn die Aktion am einfachsten über die Symbolleiste ausgeführt werden kann, beschreiben Sie diese Option. Wenn die Symbolleiste nach Ihren Wünschen angepasst werden kann und Sie Zweifel haben, unterscheidet sich die Konfiguration der Symbolleiste durch den Benutzer plötzlich von der im Thema beschriebenen. Beschreiben Sie alles so, wie es mit den Standardeinstellungen gemacht wird. Wie die Praxis zeigt, ändern die meisten normalen Benutzer selten die "Werkseinstellungen".

Wenn Sie verschiedene Möglichkeiten zum Ausführen einer Aktion in einem Thema beschreiben müssen :

Wenn in vielen Aufgabenthemen Ihres Buches eine bestimmte Aktion wiederholt wird, die auf unterschiedliche Weise ausgeführt werden kann (z. B. über ein Menü oder eine Symbolleiste), wählen Sie eine Methode aus und erwähnen Sie sie nacheinander in jedem Aufgabenthema.

Wenn es einen einfachen und kurzen alternativen Weg gibt und Sie sicherlich darüber sprechen möchten, können Sie dies im selben Schritt tun.

Beispiel: "Um die Konfiguration der virtuellen Maschine zu öffnen, wählen Sie" Aktionen ">" Konfigurieren "oder klicken Sie auf das Symbol" Konfigurieren "in der oberen rechten Ecke.").

Nummerieren Sie die Schritte, die nacheinander ausgeführt werden sollen.

Um die Beschreibung nicht aufzublähen und nicht sehr kurze Anweisungen in separaten Schritten hervorzuheben (z. B. „Klicken Sie auf OK“), können Sie zwei verwandte und verwandte Aktionen in einem Schritt kombinieren, wie unten gezeigt:



Verwenden Sie Aufzählungszeichen, um inkonsistente Aktionen hervorzuheben

Manchmal werden dem Benutzer verschiedene Möglichkeiten angeboten, um zu entscheiden, wie das Ziel erreicht werden soll. In solchen Fällen geben die vorgeschlagenen Optionen Aufzählungszeichen ab.

Zum Beispiel:


Wenn die Liste die Namen der Grafikelemente enthält, markieren Sie diese zur besseren Übersicht fett

Wenn die vom Benutzer auszuführende Aktion eine Reihe von Elementen der grafischen Oberfläche auflistet (Menüelemente, Dämmerungen usw.), starten Sie jede Option in einer neuen Zeile und markieren Sie den Namen des Elements in Fettdruck. Setzen Sie nach dem fett markierten Element einen Doppelpunkt und erläutern Sie die Beschreibung im Klartext.

Wie in diesem Beispiel gezeigt:


Wenn sich der Text im Thema mehrmals auf verschiedene Oberflächenelemente bezieht, kann es sinnvoll sein, ein separates Hilfethema zu erstellen, in dem diese Elemente beschrieben werden.

Dies ist besonders nützlich, wenn sich viele Themen im Handbuch auf dieselben Elemente beziehen. In diesem Fall müssen Sie zu Beginn des Themas einen Link zum Referenzthema angeben, in dem das erwähnte Element erläutert wird.

Wenn dieses Element später im Text noch einmal erwähnt wird, müssen Sie keinen Link mehr dazu geben - nur einen am Anfang. Wenn das Thema viele Links enthält, kann dies die Wahrnehmung und das Verständnis des Geschriebenen erschweren.

Der letzte Teil (Outro)

Outro ist die letzte Information, die nach den nummerierten Schritten kommt. Versuchen Sie, den letzten Teil kürzer zu machen - verwenden Sie nicht mehr als 3 Absätze, von denen jeder aus maximal 3 Sätzen besteht.

Verwenden Sie Outro, um die Ergebnisse oder Konsequenzen dieser Aktionen zu beschreiben.

Ein Beispiel für ein Ergebnis oder Konsequenzen kann sein:

• Informationen darüber, wo Dateien installiert wurden;

• Es wird eine Meldung angezeigt, die zusätzliche Aktionen des Benutzers erfordert.

• Einstellungen, die der Benutzer nach Abschluss der beschriebenen Aktionen ändern muss.

Im letzten Teil des Themas, wie Parallels Access nur für Wi-Fi funktioniert, heißt es beispielsweise: „ Wenn Sie Parallels Access so konfiguriert haben, dass es nur für Wi-Fi funktioniert und derzeit keine drahtlosen Netzwerke erkannt werden, werden Sie gefragt - Möchten Sie eine Verbindung über 3G herstellen? ".

Im letzten Teil des Themas können Sie einen alternativen Weg beschreiben, um die Aufgabe abzuschließen.

Wenn die alternative Methode in einem Satz beschrieben werden kann, können Sie dies im letzten Teil des Themas tun.

Outro kann weitere Informationen zur aktuellen Aufgabe bereitstellen.

Diese Informationen können Benutzer darüber informieren, was sie nach Abschluss der beschriebenen Aufgabe noch tun können.

Im folgenden Beispiel wird im Thema beschrieben, wie Sie eine Datei von einer virtuellen Maschine in macOS Finder finden. Im letzten Teil des Themas wird beschrieben, was der Benutzer mit der Datei noch tun kann, nachdem die Datei gefunden wurde.



In Outro können Sie zusätzliche Informationen beschreiben, die nur einige Benutzer benötigen.

Im letzten Teil des Themas zur Integration von virtuellen Windows-Maschinen in macOS können Sie beispielsweise Folgendes schreiben: „Wenn Sie ein MacBook Pro 2016 oder höher haben, können Sie mit einigen Windows-Anwendungen über die Touch-Leiste arbeiten.“


Teilen Sie lange Aufgaben in kurze Phasen auf

Grundsätzlich sind Aufgabenthemen kurz und passen auf eine Seite. Wenn jedoch eine komplexe und sehr lange Aufgabe beschrieben wird, die in Stufen, Stufen und Verfahren unterteilt werden kann, lohnt es sich, die Informationen logisch zu trennen und jede Stufe in einem separaten Thema zu beschreiben, damit die Beschreibung einfacher, besser lesbar und verständlicher aussieht.

Das Folgende ist ein Beispiel aus dem Inhalt des Parallels Desktop-Benutzerhandbuchs. Der Screenshot zeigt ein Kapitel, in dem verschiedene Möglichkeiten zur Installation von Windows in einer virtuellen Maschine beschrieben werden. Eine der Möglichkeiten, Daten von einem Remotecomputer zu importieren, ist in mehrere Themenbereiche unterteilt.



Fortsetzung folgt…

(Im nächsten Teil werden wir mehr über konzeptionelle Themen und Referenzthemen sowie Themen zur Problemlösung sprechen.)