Schlechter Rat: Wie schreibe ich technische Dokumentation? Teil drei und zuletzt

Tipps zum kompetenten Verfassen technischer Dokumentationen für Benutzer.
Teil 3 (endgültig)

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



Dieses Mal werden wir genauer betrachten:

• konzeptionelle Themen (Konzeptseiten);
• Referenzthemen (Referenzseiten);
• Themen, die erklären, wie ein Problem gelöst werden kann (Seiten zur Fehlerbehebung);
• wo und wie Screenshots verwendet werden;
• und geben Sie auch ein paar Tipps für diejenigen, die Dokumentation auf Englisch schreiben.

Vorherige Teile: unser Ansatz zur Dokumentation und Lokalisierung; Dokumentationstipps Teil 1 und Teil 2 .

Konzeptthemen (Konzeptseiten)

Solche Themen werden benötigt, um Benutzern zusätzliche technische Informationen bereitzustellen und damit das Aufgabenthema nicht zu überlasten.

Bitte beachten Sie, dass sie genau zusätzliche Informationen enthalten sollten, aber keine Möglichkeit, das Problem zu lösen.

Konzeptionelle Themen sind gut zu verwenden, um:

• erzählen, wie ein bestimmter Prozess funktioniert;
• Beschreiben Sie, welche neuen Funktionen in dieser Version des Produkts hinzugefügt wurden.
• dem Benutzer zusätzliche Informationen zur Verfügung stellen, die ihm helfen, eine Entscheidung zu treffen;
• Sagen Sie, was der Benutzer in Ihrer Anwendung tun kann.

Beispielsweise kann das Thema „Informationen zu virtuellen Maschinen“ beschreiben, was es ist und wie es funktioniert. Dieses Thema sollte jedoch keine Anweisungen zum Erstellen einer virtuellen Maschine enthalten - dies sollte im Aufgabenthema beschrieben werden.

So wird sich ein erfahrener Benutzer beim Lesen eines Aufgabenthemas nicht beschweren: "Warum malen Sie mich, was es ist, ich weiß bereits ...". Und diejenigen, die es nicht wissen, werden einen Link zu einem konzeptionellen Thema sehen und lesen.

In der Regel beginnen konzeptionelle Themenüberschriften mit:

• "Über (etwas)" ("Über virtuelle Maschinen");
• "Was …?" ("Was ist eine virtuelle Maschine?");
• "Wie funktioniert es (etwas)?" ("Wie funktioniert eine virtuelle Maschine?");
• „Grundlagen der virtuellen Maschine verstehen“ usw.

Hier ist ein Beispiel für ein konzeptionelles Thema aus der englischen Dokumentation:



Referenzthemen (Referenzseiten) :

Solche Themen beschreiben verschiedene Referenzinformationen, auf die der Benutzer bei Bedarf zugreifen kann.

Gute Beispiele für solche Themen sind:

• "Glossar" am Ende des Handbuchs;
• Ein Thema, in dem Sie beschreiben, welche Elemente im Menü verfügbar sind und was sie tun, welche Tastaturkürzel Sie bei der Arbeit mit dem Programm verwenden können, welche Symbole in der Taskleiste verfügbar sind usw.

Hier ist ein Beispiel für ein Thema, das GUI-Symbole beschreibt:



Themen, die beschreiben, wie ein Problem gelöst werden kann (Seiten zur Fehlerbehebung)


Solche Themen helfen dem Benutzer, ein Hindernis zu überwinden oder ein Problem zu lösen. Bei Themen zur Fehlerbehebung können folgende Szenarien auftreten:

• Der Benutzer hat ein Problem und möchte es lösen. Beispiel: "Mein USB-Gerät funktioniert in einer virtuellen Maschine nicht".
• Der Benutzer hat versucht, etwas zu tun, und ist fehlgeschlagen. Beispiel: "Ich kann Parallels Desktop nicht aktivieren" ("Ich kann Parallels Desktop nicht aktivieren").
• Es gibt eine Bedingung oder Bedingung, die der Benutzer ändern möchte. Zum Beispiel "Windows ist langsam" ("Windows scheint langsam").

Was ist und was nicht Fehlerbehebung :

Wenn der Benutzer etwas tun möchte, aber nicht weiß, wie, sollte dies nicht in der Fehlerbehebung, sondern im Aufgabenthema beschrieben werden.

Die Fehlerbehebung impliziert, dass der Benutzer versucht hat, etwas zu tun (gemäß den Anweisungen des Aufgabenthemas), aber es gab ein Problem, und der Benutzer weiß nicht, wie er es lösen soll.

Ein Thema, das beschreibt, wie ein externes Laufwerk in einem Gastbetriebssystem verwendet wird, ist beispielsweise ein Aufgabenthema.

Das Thema, das die möglichen Probleme beschreibt - "Ich habe Probleme beim Anschließen einer Festplatte" - ist ein Thema zur Fehlerbehebung. Sein Inhalt impliziert, dass der Benutzer den Anweisungen gefolgt ist, aber aus irgendeinem Grund keinen Erfolg hatte.

Wenn Sie ein Aufgabenthema schreiben und ein Schritt in der Anleitung geringfügige Schwierigkeiten verursachen kann, kann es im selben Schritt oder Thema beschrieben werden. Bei kleineren Schwierigkeiten ist es nicht erforderlich, ein separates Thema zur Fehlerbehebung zu schreiben.

Am Ende des Themas, in dem beschrieben wird, wie Tastaturkürzel geändert werden, können Sie beispielsweise Folgendes hinzufügen: "Einige Tastenkombinationen können nicht bearbeitet oder gelöscht werden."

Themen zur Fehlerbehebung

In der Regel haben Themen zur Fehlerbehebung eine ähnliche Struktur wie Aufgabenthemen.

Sie bestehen aus:

• Titel ("Titel")
• Einführungsteil ("Intro")
• Einleitende Phrase, nach der nummerierte Schritte oder notwendige Informationen („Schrittüberschrift“) beginnen
• Informationen, die zur Lösung eines Problems benötigt werden („Schritte zur Lösung“)
• Der letzte Teil ("outro")

Titel (Seitentitel)

Es ist gut, wenn die Kopfzeile des Themas zur Fehlerbehebung das Problem des Benutzers aus der ersten Person ausdrückt. Zum Beispiel:

• "Ich kann Parallels Desktop nicht aktivieren" ("Ich kann Parallels Desktop nicht aktivieren")
• "Windows ist langsam" ("Windows scheint langsam")
• "Eine Meldung besagt, dass keine virtuellen Maschinen erkannt wurden" wird angezeigt

Wenn Sie eine Dokumentation in englischer Sprache verfassen, sollten Sie im Titel die Großschreibung im Titelstil verwenden (Großschreibung siehe Details am Ende des Artikels):

Richtig: Mein USB-Gerät funktioniert nicht

Falsch: Mein USB-Gerät funktioniert nicht

Einführung (Intro)

Geben Sie den Benutzern unmittelbar nach der Überschrift die Informationen, die sie zuerst wissen müssen.

Zum Beispiel:

• Erläutern Sie die wahrscheinlichste Ursache des Problems. Wenn es viele Gründe geben kann, beschreiben Sie alle möglichen.
• Manchmal können Sie allgemein beschreiben, was zur Lösung eines Problems getan werden muss. Es ist im Allgemeinen - detaillierte Anweisungen sollten in Schritten zur Lösung gegeben werden.

Einleitende Phrase (Schrittüberschrift)

Schreiben Sie vor der Abfolge der Schritte, die Sie zur Lösung des Problems ausführen müssen, einen einleitenden Satz. Vergessen Sie nicht, am Ende einen Doppelpunkt zu setzen.

Wenn die Lösung des Problems eine Reihe von aufeinander folgenden Aktionen ist:

In solchen Fällen sollte der einleitende Satz nach den gleichen Grundsätzen wie für die Aufgabenthemen (siehe den zweiten Teil der Tipps) erfolgen, dh die gleichen Wörter wie in der Aufgabenformulierung verwenden.

Sie schreiben beispielsweise ein Thema zur Fehlerbehebung, in dem Sie erklären, warum der Benutzer die Konfiguration der virtuellen Maschine nicht öffnen kann (der Menüpunkt ist abgeblendet und inaktiv):

Titel: "Ich kann die Einstellungen der virtuellen Maschine nicht öffnen"

Einführung: „Wenn Sie die Einstellungen der virtuellen Maschine nicht öffnen können (der Menüpunkt ist ausgegraut), liegt der wahrscheinlichste Grund darin, dass die virtuelle Maschine nicht ausgeschaltet ist.“

Ferner der einleitende Satz: „So öffnen Sie die Einstellungen der virtuellen Maschine:“ (in diesem Satz werden dieselben Wörter verwendet wie in der Formulierung der auszuführenden Aufgabe).

Und dann gibt es Schritte - 1) Stellen Sie sicher, dass die Maschine ausgeschaltet ist. Wenn es funktioniert, klicken Sie dort und dort. 2) Dann mach das.

Wenn das Problem mehrere Lösungen hat:

In solchen Fällen sollte der einleitende Satz die folgenden Wörter enthalten:

- "Probieren Sie diese Lösungen aus",
- "versuchen Sie Folgendes",
- "stellen Sie sicher, dass" usw.

Hier einige Beispiele aus der englischen Dokumentation:

Seitentitel: Ich kann Parallels Desktop nicht aktivieren
Aufgabenabdeckungen: Eine Liste der zu überprüfenden Dinge
Schrittüberschrift: Wenn Sie Probleme beim Aktivieren von Parallels Desktop haben, stellen Sie sicher, dass ...

Seitentitel: Windows scheint langsam zu sein
Aufgabenabdeckungen: Eine Liste der Dinge, die Sie ausprobieren sollten
Schrittüberschrift: Wenn die Windows-Leistung langsam erscheint, versuchen Sie Folgendes ...

Seitentitel: In einer Nachricht wird "Keine Macs verbunden" angezeigt.
Aufgabenabdeckungen: Verschiedene Dinge, die überprüft oder versucht werden müssen
Schrittüberschrift: Wenn Sie Ihren Mac nicht in der Liste der Macs sehen

Informationen zur Lösung des Problems (Schritte zur Lösung)

Dieser Abschnitt enthält alles, was der Benutzer wissen und / oder unternehmen muss.

Wenn es mehrere Lösungen gibt:
Beschreiben Sie in solchen Fällen jede Methode mit Aufzählungszeichen (mehr dazu im zweiten Teil der Tipps). Wenn eine Methode kompliziert ist und Sie sie bereits in einem anderen Thema ausführlich beschrieben haben, geben Sie einfach einen Link an.

Wenn das, was Sie tun müssen, bereits irgendwo in einem anderen Thema beschrieben ist:
Geben Sie einfach einen Link zu diesem Thema.

Wenn es keine spezifische Anweisung gibt, was könnte getan werden, um das Problem zu lösen:
Geben Sie zusätzliche Informationen an, die dem Benutzer helfen können, herauszufinden, was das Problem verursachen könnte.

Fazit (outro)

Abschließend können Sie zusätzliche Informationen zur Aufgabe oder mögliche Lösungen für das Problem bereitstellen. Weitere Informationen zur Verwendung von Outro finden Sie in Teil 2 der Tipps .

Verwenden von Grafiken (Screenshots, Diagramme, Diagramme usw.)

Screenshots und Diagramme können Benutzern helfen, besser zu verstehen, was in dem Thema geschrieben steht.

Wann man Grafiken verwendet:

Bei jedem Schritt müssen Sie keinen Screenshot einfügen. Der Benutzer weiß einfach nicht, wo er suchen soll, und vergleicht ständig den Bildschirm und den Screenshot.

Screenshots sollten eingefügt werden, wenn sie wesentlich zum Verständnis der Anweisungen beitragen.

Zum Beispiel:

• Wenn Sie eine Schaltfläche oder ein Symbol anzeigen müssen, das / das keinen Namen in der Gua hat oder nicht sofort ins Auge fällt, oder wenn mehrere ähnliche auf dem Bildschirm angezeigt werden;
• Wenn Sie einen Kontext für die Aufgabe oder eine klare visuelle Erklärung dafür bereitstellen müssen, wie und wie sie am Ende aussehen wird;
• Wenn der Screenshot es Ihnen ermöglicht, etwas schnell zu verstehen oder zu erklären, das eine zu lange und komplizierte Erklärung in Worten erfordert.

Wo und wie wird der Zeitplan platziert:

Im Folgenden finden Sie einige Empfehlungen, wo und wie Sie Grafiken auf der Seite platzieren.

1) Wenn der Screenshot die konzeptionellen Informationen oder das Ergebnis der Aufgabe widerspiegelt, können Sie sie in oder nach dem Intro einfügen.

Hier ist ein Beispiel aus der englischen Dokumentation, die ein Thema zeigt, das den Fenstermodus von Windows beschreibt. Ein Screenshot, der zeigt, was nach dem Einfügen eines solchen Schalters nach der Einführung und vor der Anweisung selbst passiert, wie in diesen Modus gewechselt wird:



2) Wenn sich der Screenshot auf einen bestimmten Schritt in der Anleitung bezieht, fügen Sie ihn nach oder innerhalb dieses Schritts ein:



Wenn Sie einen Screenshot einer Schaltfläche, eines Symbols oder eines anderen Schnittstellenelements einfügen müssen, müssen Sie ihn nach dem Namen dieses Elements einfügen:



Verwenden Sie keine Grafiken, um offensichtliche Dinge zu veranschaulichen.

Verwenden Sie keine Screenshots, um Folgendes zu veranschaulichen:

• Menü
• Symbole, Schaltflächen und Registerkarten, die einen Namen haben
• Alles andere, was sich leicht und leicht in Worten beschreiben lässt.

Zusätzliche Tipps für diejenigen, die Dokumentation auf Englisch schreiben:


1) So aktivieren Sie Titel:

Großschreibung Es stehen drei Arten der Großschreibung zur Verfügung: Satzstil, Titelstil und Großbuchstaben.

• Großschreibung im Satzstil: Diese Zeile enthält ein Beispiel für die Großschreibung im Satzstil.
• Großschreibung im Titelstil: Diese Zeile enthält ein Beispiel für die Großschreibung im Titelstil.
• Alle Kappen: DIESE LINIE BIETET EIN BEISPIEL FÜR ALLE KAPPEN.

Verwenden Sie nicht alle Kappen zur Hervorhebung.

Großschreibung (Satzstil): Wenn Sie die Großschreibung im Satzstil verwenden, schreiben Sie den ersten Buchstaben des ersten Wortes sowie den ersten Buchstaben aller Eigennamen und Adjektive in Großbuchstaben.
Großschreibung (Titelstil): Verwenden Sie die Großschreibung im Titelstil für Buchtitel, Teiletitel, Kapiteltitel und Abschnittsüberschriften (Textköpfe).

Befolgen Sie diese Regeln, wenn Sie die Titel-Großschreibung verwenden. Großschreiben Sie jedes Wort außer:

• Artikel (a, an, the), es sei denn, ein Artikel ist das erste Wort oder folgt einem Doppelpunkt
• Koordinierende Konjunktionen (und, aber, oder, noch, für, noch und so)
• Das Wort in Infinitiven (So schließen Sie Ihren Drucker an)
• Das Wort als, unabhängig vom Wortart
• Wörter, die immer mit Kleinbuchstaben beginnen, z. B. iPhone und iPad.
• Präpositionen von vier Buchstaben oder weniger (an, durch, für, von, in, in, von, aus, an, auf, aus, über, auf, auf und mit), außer wenn das Wort Teil einer Verbalphrase ist. Zum Beispiel:
  
  Starten Sie das ComputerLog
  In den ServerGet
  Begonnen mit Parallels Desktop

Großschreibung:

• Das erste und letzte Wort, unabhängig vom Wortart:
Für Linux-Benutzer

Wofür sind Parallelen-Tools?

• Das zweite Wort in einer Verbindung mit Bindestrich:

Richtig: Ereignisse auf hoher Ebene, 32-Bit-Adressierung
Falsch: Ereignisse auf hoher Ebene, 32-Bit-Adressierung
Ausnahmen: Eingebaut, Plug-In

• Die Wörter sind, wenn, ist, es, als, das und das

2) Wie man das Wort "Klick" verwendet:

Klicken Klicken Sie auf Klicken, um den Vorgang des Positionierens des Zeigers auf einem Objekt auf dem Bildschirm und des kurzen Drücken und Loslassens der Maustaste zu beschreiben. Verwenden Sie nicht Klicken auf. Da die meisten Benutzer wissen, was Klicken ist, müssen Sie es nur in der Dokumentation definieren, die für Anfänger gedacht ist, z. B. in Tutorials.
Richtig: Klicken Sie auf Mac, wenn Sie das USB-Gerät mit Mac OS X verwenden möchten.

Falsch: Zeigen Sie auf den Mac und klicken Sie darauf, wenn Sie das USB-Gerät in Mac OS X verwenden möchten.
Klicken Sie auf Nicht verwenden. benutze Klick.

3) E-Mail oder E-Mail?

Verwenden Sie E-Mail. Verwenden Sie keine E-Mail.

4) Wenn oder ob?

Verwenden Sie if, um eine Bedingung auszudrücken. Verwenden Sie, um Alternativen auszudrücken.
Richtig: Überprüfen Sie, ob Parallels Tools installiert wurden.
Falsch: Überprüfen Sie, ob Parallels Tools installiert wurden.
Richtig: Klicken Sie auf Mac, wenn Sie das USB-Gerät mit Mac OS X verwenden möchten.

5) Verwendung von Produktnamen:

Befolgen Sie den Großschreibstil auf der Produktverpackung. Verwenden Sie den vollständigen Produktnamen für das erste Auftreten in einem Textabschnitt (z. B. einem Kapitel). Verwenden Sie anschließend gegebenenfalls eine verkürzte Version des Produktnamens.

Beispiel: Parallels Desktop 14 für Mac: Verwenden Sie beim ersten Auftreten in einem Textabschnitt Parallels Desktop 14 für Mac.

Verwenden Sie bei späteren Ereignissen Parallels Desktop.

Fazit

In diesen drei Teilen des Handbuchs haben wir versucht, die Tipps zusammenzustellen, zusammenzufassen und zu strukturieren, die Ihre Dokumentation einfacher und verständlicher machen.

Wir bestehen nicht darauf, dass das Schreiben auf diese Weise notwendig ist - es gibt viele Ansätze für Dokumentation und Techniken. Schauen Sie sich die Einstellung an und verwenden Sie die, die zu Ihnen passen.

Vielen Dank für Ihre Aufmerksamkeit und Ihr Interesse!