Tipps zum kompetenten Verfassen technischer Dokumentationen für Benutzer.
Teil 1
In einem früheren Artikel haben wir beschrieben, wie der Prozess der
Dokumentation und Lokalisierung unserer Produkte abläuft.
Dieses Mal finden Sie das Handbuch
unseres technischen Redakteurs Andrei Starovoitov, mit dem Sie Ihre Dokumentation einfacher und benutzerfreundlicher gestalten können (die beschriebenen Techniken werden von Apple, Microsoft und anderen Unternehmen zur Dokumentation Ihrer Produkte verwendet).
Wie Sie wissen, ist eine gute Dokumentation kein Luxus, sondern ein Mittel zur Steigerung des Umsatzes des Unternehmens. Wenn Sie ein Programm starten oder bereits entwickeln möchten, benötigen Sie für den Eintritt in den Weltmarkt ein Benutzerhandbuch (auch bekannt als Benutzerhandbuch) oder zumindest ein Dokument, in dem die Kunden erfahren, wie sie mit Ihrem Produkt arbeiten sollen (das sogenannte Programm) Erste Schritte mit).
In welcher Sprache Sie die Dokumentation schreiben - auf Russisch und dann übersetzen oder sofort auf Englisch - entscheiden Sie. Bei Parallels haben wir den zweiten Ansatz gewählt. Es ist oft viel einfacher, eine Beschreibung auf Englisch zu erstellen, da fast alle (und jetzt können wir sagen, dass "alle") Computerbegriffe auf Russisch ausgeliehen sind.
Weiter im Text werden wir uns sowohl auf russische als auch auf englische Beispiele konzentrieren.
Worauf sollten Sie beim Schreiben von Dokumentationen achten?
Arten von Themen in der Dokumentation
Wenn Sie ein Thema schreiben, müssen Sie zuerst bestimmen, um welche Art von Thema es sich handelt :)
Davon hängt ab, was und wie man darin schreibt.
Es gibt
4 Haupttypen von Themen :
•
Themen, die beschreiben, wie eine bestimmte Aufgabe oder mehrere verwandte Aufgaben gelöst werden (auf Englisch wird diese Art von Thema als
Aufgabenseiten bezeichnet) .
Beispiel: "Parallels Desktop installieren" oder "Windows herunterfahren oder anhalten". Jedes dieser Themen beschreibt eine Reihe von einem oder mehreren Schritten, die ein Benutzer ausführen muss, um ein bestimmtes Ziel zu erreichen. Das Benutzerhandbuch besteht hauptsächlich aus solchen Themen.
Normalerweise lesen Benutzer nicht gerne, besonders wenn viel Text vorhanden ist. Daher sollten Sie versuchen, solche Themen so kurz wie möglich zu halten. Wenn die Informationen in der folgenden Form dargestellt werden: „Sie können etwas tun, klicken Sie einfach hier und hier“ (Aufgabenthemen werden im nächsten Teil des Artikels ausführlicher behandelt).
Wenn der Entwickler der Ansicht ist, dass der Benutzer zusätzliche Informationen wissen muss und viele davon vorhanden sind, wird dies am besten in konzeptionellen Themen beschrieben (siehe unten).
•
Konzeptionelle Themen (auf Englisch -
Konzeptseiten ). In diesen Themen gibt es keine Anweisungen zur Lösung eines Problems. Sie enthalten Informationen, die eher zu einem besseren Verständnis der Dinge beitragen. Zum Beispiel werden konzeptionelle Themen verwendet, um:
- Erklären Sie den Benutzern genau, wie ein Prozess funktioniert.
- Sagen Sie, was in den Anwendungseinstellungen getan werden kann.
- die zusätzlichen Funktionen in der neuen Version des Produkts beschreiben;
- Bereitstellung zusätzlicher Informationen, die dem Benutzer helfen, ein Problem besser zu verstehen oder zu lösen.
Bitte beachten Sie, dass zusätzliche Informationen (falls es viele davon gibt) genau im konzeptionellen Thema angegeben werden müssen, um das Aufgabenthema nicht zu überladen.
•
Hilfethemen (auf Englisch -
Referenzseiten ) - enthalten Informationen, auf die der Benutzer regelmäßig zurückgreifen kann, um herauszufinden, was ein bestimmter Begriff bedeutet, wie eine Funktion funktioniert usw. Ein gutes Beispiel für solche Themen ist das Wörterbuch am Ende des Handbuchs (auch bekannt als Glossar). Referenzthemen sind besonders nützlich, um den Zweck verschiedener Schnittstellenelemente zu erläutern.
•
Themen, die beschreiben, wie ein Problem gelöst werden kann (auf Englisch -
Seiten zur Fehlerbehebung ).
Beispiel: "Ich kann Parallels Desktop nicht aktivieren" oder "Ich kann keine Verbindung zum Internet herstellen." Diese Themen beschreiben, was zur Lösung eines Problems getan werden muss. Sie können auch Informationen enthalten, die helfen, die Ursache der Fehlfunktion zu verstehen.
Grundlegende Anweisungen für alle Arten von Dokumentation
Beim Erstellen eines Leitfadens:
1)
Konzentrieren Sie sich auf den Benutzer
• Anstatt die Produktbeschreibung anhand ihrer Funktionen oder Oberflächenelemente zu strukturieren, sollten Sie sich auf die Aufgaben konzentrieren, die der Benutzer am wahrscheinlichsten zu lösen versucht.
Ein Thema zum Schutz von Daten in einer virtuellen Maschine kann beispielsweise auf zwei Arten aufgerufen werden:
a) „Sicherheitseinstellungen“, in denen detailliert beschrieben wird, wie Daten geschützt werden können.
b) Machen Sie mehrere Themen, die bestimmte Aufgaben beschreiben:
- "Schützen Sie Ihre Daten mit Antivirensoftware"
- "Sichern Sie Ihre virtuelle Maschine" ("Sichern Sie Ihre virtuelle Maschine")
Nach den aktuellen Trends in der Dokumentation ist der zweite Ansatz vorzuziehen, da der Benutzer in diesem Fall nicht raten muss, ob er etwas tun soll oder nicht, und klare Anweisungen erhält, was genau zu tun ist.
• Konzentrieren Sie sich auf die Aufgaben des Benutzers und seine technische Kompetenz.
In der Dokumentation für den durchschnittlichen Benutzer sollten Sie beispielsweise anstelle von "Erstellen einer virtuellen Maschine" "Windows oder ein anderes Betriebssystem installieren" als " virtuelle Maschine “ist allen nicht bekannt. Oder ein anderes Beispiel - ein Thema, das beschreibt, wie schnelle Tastaturkürzel erstellt werden. Es ist besser, "Tastaturkürzel konfigurieren" als "Tastatureinstellungen" zu bezeichnen.
Für die Mehrheit der Leser von Habr wäre es zwar klarer, "Verknüpfungen konfigurieren", aber die Frage ist bereits, wie sehr ein solcher Begriff derzeit in der offiziellen Terminologie angemessen ist :)
• Wenn dies nicht klar ist, erklären Sie, warum der Benutzer möglicherweise eine bestimmte Aufgabe ausführen muss.
Zum Beispiel:
• Versuchen Sie bei der Beschreibung, die Wörter zu verwenden, die der Benutzer jeden Tag in seiner Rede verwendet. Wenn ein technisch komplexer Begriff durch einfachere Wörter ersetzt werden kann, versuchen Sie immer, einfachere Wörter zu verwenden.
Zum Beispiel "transparent" statt "transparent". Wenn Sie ein Beispiel aus der englischen Sprache geben, verwenden Sie "verwenden" anstelle von "verwenden".
2)
Versuchen Sie, alle notwendigen Informationen ohne unnötige Worte zu geben„Botschafter von der Insel Samos kamen nach Sparta, um um Hilfe zu bitten. Sie hielten eine lange und schöne Rede. Die Spartaner sagten: "Nachdem wir das Ende gehört hatten, vergaßen wir den Anfang und vergaßen den Anfang, verstanden wir das Ende nicht." Samosets waren schlagfertig. Am nächsten Tag kamen sie mit einem leeren Beutel zum Treffen und sagten nur vier Worte: "Es gibt einen Beutel, es gibt kein Mehl." Die Spartaner schalt sie - zwei Worte waren genug: "Es gibt kein Mehl", aber sie waren mit so schnellem Verstand zufrieden und versprachen zu helfen. "Wenn Sie die Funktionalität zu lange beschreiben, wird sie niemand lesen. Aber es ist auch komplett "spartanisch", denn wenn zu wenig geschrieben wird, gibt es Fragen und Zweifel, und die Benutzer werden anfangen, das Support-Team zu ziehen. Im Allgemeinen ist es wichtig, das Gleichgewicht zu halten.
Damit Benutzer alle benötigten Informationen finden und gleichzeitig jeden Abschnitt so kurz wie möglich beschreiben können:
- Konzentrieren Sie sich auf die wichtigsten Informationen, die zur Lösung des im Thema beschriebenen Problems erforderlich sind. Wenn einige Details für die Aufgabe nicht erforderlich sind, beschreiben Sie sie nicht.
- Sie müssen nicht jeden Klick dokumentieren. Wenn in der Benutzeroberfläche alles klar ist, lassen Sie den Benutzer es selbst herausfinden. Anstatt beispielsweise jeden Schritt der Programminstallation zu dokumentieren, ist es besser zu schreiben: "Befolgen Sie zum Installieren des Programms die Anweisungen auf dem Bildschirm." Wenn Sie als letzte Phase eines Vorgangs auf OK klicken müssen, ist dies ebenfalls keine Beschreibung wert.
- Anstatt alle Informationen in einem Thema anzugeben, zeigen Sie dem Benutzer, wo Sie zusätzliche Informationen über Links zu anderen Themen, Links zu externen Ressourcen lesen oder am Ende den Abschnitt „Verwandte Informationen“ einfügen können, der Links zu enthält Themen im Zusammenhang mit dem, was auf dem Bildschirm beschrieben wird.
- Wenn eine lange Aufgabe in mehrere Phasen oder Unteraufgaben unterteilt werden kann, von denen jede eine separate Aufgabe ist, teilen Sie das Thema in die entsprechenden Abschnitte auf oder erstellen Sie einen Abschnitt im Handbuch, der aus Themen besteht, die jede Phase beschreiben. Vergessen Sie in diesem Fall nicht, Links zu verwandten Themen einzufügen.
- Wenn eine Aufgabe (z. B. das Starten einer virtuellen Maschine) auf verschiedene Arten ausgeführt werden kann, müssen sie nicht alle beschrieben werden. Es genügt, den schnellsten und einfachsten Weg zu erwähnen. Wenn Sie immer noch der Meinung sind, dass es für den Benutzer nützlich ist, eine andere Methode zu kennen, beschreiben Sie diese am Ende (auf Englisch - Outro).
3)
Wiederholen Sie nicht die gleichen Informationen auf den Seiten
Anstatt Informationen in jedem Thema zu wiederholen, die bereits in einem anderen Thema beschrieben wurden, ist es besser, darauf zu verweisen, dass eine detailliertere Beschreibung in einem solchen Thema zu finden ist, oder einfach einen Hyperlink dazu zu geben.
4)
Machen Sie den Benutzer richtig auf sich aufmerksam
Wenn die Beschreibung die Aufmerksamkeit des Benutzers auf sich ziehen muss, werden die folgenden einleitenden Wörter verwendet: „Achtung! (auf Englisch - Warnung!), "Wichtig:" (auf Englisch - Wichtig :) und "Hinweis:" (auf Englisch - Hinweis :).
Jedes dieser Wörter impliziert seine eigene "Wichtigkeit".
Verwenden Sie jeden Begriff richtig, um den Benutzer nicht umsonst zu belasten:
- Achtung! (Warnung! Auf Englisch), um auf eine gefährliche Situation hinzuweisen, die, wenn sie nicht vermieden wird, zu Datenverlust, Schäden an Bauteilen oder anderen Schäden führen kann.
- Verwenden Sie "Wichtig:" (auf Englisch - Wichtig :), um auf eine signifikante und möglicherweise problematische Situation hinzuweisen, die jedoch nicht zu physischen Schäden, Schäden oder Datenverlust führen kann.
- Verwenden Sie "Hinweis:" (Hinweis :), um zusätzliche Informationen zu diesem Thema bereitzustellen. Obwohl eine solche Einfügung Benutzer von der aktuellen Aufgabe trennt, kann sie nützlich sein.
Zum Beispiel:
Klicken Sie zum Öffnen der Konfiguration der virtuellen Maschine auf Aktionen> Konfigurieren.
Hinweis: Die virtuelle Maschine muss ausgeschaltet sein.
Verwenden Sie den Hinweis „Hinweis:“ sparsam - wenn Sie ihn zu oft einfügen, verstopft er den Text und hört auf, darauf zu achten.
Fügen Sie nach Möglichkeit am Anfang des Themas "Achtung!", "Wichtig:" und "Hinweis:" ein, damit der Benutzer dies erfährt, bevor er mit der Durchführung eines Verfahrens beginnt. Wenn sich die Informationen jedoch nur auf einen bestimmten Schritt beziehen, fügen Sie sie nach diesem Schritt ein.
Ein Beispiel:
Fortsetzung folgt…(Im nächsten Teil des Artikels werden wir detailliertere Themen behandeln, die beschreiben, wie ein bestimmtes Problem gelöst werden kann.)