Benutzerdokumentation: Was macht sie schlecht und wie kann man das beheben

Die Dokumentation zur Software ist einfach eine Ansammlung von Artikeln. Doch selbst die können einem auf die Nerven gehen. Zuerst sucht man lange nach der benötigten Anleitung. Dann kämpft man sich durch unverständlichen Text. Man handelt wie beschrieben, und das Problem bleibt ungelöst. Man sucht nach einem anderen Artikel, wird nervös... Nach einer Stunde wirft man alles hin und geht. So funktioniert schlechte Dokumentation. Was sie so macht und wie man es ändern kann - lesen Sie weiter unten.

In unserer alten Dokumentation gab es viele Mängel. Schon seit fast einem Jahr arbeiten wir daran, sie zu überarbeiten, damit das oben beschriebene Szenario unsere Kunden nicht betrifft. Schauen Sie sich an, wie es war und wie es ist.

Problem 1. Unverständliche, schlecht geschriebene Artikel

Wenn man sich in der Dokumentation nicht zurechtfindet, was hat sie dann für einen Sinn? Aber niemand schreibt absichtlich unverständliche Artikel. Sie entstehen, wenn der Autor nicht an das Publikum und das Ziel denkt, viel „Wasser” lässt und den Text nicht auf Fehler überprüft.

• Das Publikum. Vor dem Schreiben eines Artikels sollte man über das Kenntnisniveau des Lesers nachdenken. Es ist logisch, dass man in einem Artikel für Anfänger die grundlegenden Schritte nicht weglassen und technische Begriffe nicht ohne Erklärung lassen sollte, während man in einem Artikel über eine seltene Funktion, die nur für Profis nützlich ist, nicht die Bedeutung des Begriffs PHP ausführen sollte.
• Ziel. Ein weiterer Punkt, über den man besser im Voraus nachdenkt. Der Autor sollte sich ein klares Ziel setzen, die nützliche Handlung des Artikels definieren und entscheiden, was der Leser nach dem Lesen tun wird. Wenn man das nicht macht, erhält man eine Beschreibung um der Beschreibung willen.
• Überflüssige Informationen und Fehler. Zu viele überflüssige Informationen und Bürokratisches, Fehler und Tippfehler beeinträchtigen das Verständnis. Selbst wenn der Leser kein Grammatikfanatiker ist, kann Nachlässigkeit im Text ihn abstoßen.

Berücksichtigen Sie die oben genannten Tipps, und die Artikel werden verständlicher - garantiert. Um es noch besser zu machen, beachten Sie unsere 50 Fragen bei der Erstellung technischer Dokumentation.

Problem 2. Artikel beantworten nicht alle Fragen

Es ist schlecht, wenn die Dokumentation mit der Entwicklung nicht Schritt hält, nicht auf reale Fragen antwortet und Fehler jahrelang nicht behoben werden. Das sind Probleme, die weniger mit dem Autor als mit der Organisation der Prozesse innerhalb des Unternehmens zu tun haben.

Die Dokumentation hält nicht mit der Entwicklung Schritt

Die Funktion ist bereits veröffentlicht, das Marketing plant ihre Bekanntmachung, und hier stellt sich heraus, dass der neue Artikel oder die Übersetzung immer noch nicht in der Dokumentation vorhanden ist. Aufgrund dessen mussten wir sogar die Veröffentlichung verschieben. Man kann die Kollegen so oft wie möglich bitten, die Aufgaben rechtzeitig an die technischen Redakteure weiterzugeben, aber das wird nicht funktionieren. Wenn der Prozess nicht automatisiert wird, wird sich die Situation wiederholen.

Wir haben Änderungen in YouTrack vorgenommen. Die Aufgabe zum Schreiben eines Artikels über die neue Funktion fällt dem technischen Redakteur genau in dem Moment zu, wenn die Möglichkeit getestet wird. Zu diesem Zeitpunkt wird auch das Marketing informiert, um sich auf die Promotion vorzubereiten. Benachrichtigungen kommen auch in den Unternehmensmessenger Mattermost, sodass man die Neuigkeiten von den Entwicklern einfach nicht übersehen kann.

Die Dokumentation spiegelt nicht die Anforderungen der Benutzer wider

Wir sind es gewohnt, so zu arbeiten: Die Funktion wurde veröffentlicht, wir haben darüber informiert. Wir haben beschrieben, wie man sie aktiviert, deaktiviert und feineinstellungen vornimmt. Aber was, wenn der Kunde unsere Software anders benutzt, als wir es angenommen haben? Oder es treten Fehler auf, an die wir nicht gedacht haben?

Um die Dokumentation so vollständig wie möglich zu halten, empfehlen wir, die Anfragen im Support, die Fragen in thematischen Foren und die Suchanfragen zu analysieren. Die beliebtesten Themen sollten den technischen Redakteuren übergeben werden, damit sie bestehende Artikel ergänzen oder neue schreiben.

Die Dokumentation wird nicht weiterentwickelt

Es ist schwierig, es sofort perfekt zu machen, Fehler werden immer vorkommen. Man kann auf Feedback von Kunden hoffen, aber es ist unwahrscheinlich, dass sie jede kleine Schreibfehler, Ungenauigkeit, unklare oder nicht gefundene Artikel melden. Neben den Kunden lesen auch die Mitarbeiter die Dokumentation, und sie sehen die gleichen Fehler. Das kann man nutzen! Man muss nur Bedingungen schaffen, unter denen es einfach ist, ein Problem zu melden.

Wir haben eine Gruppe auf dem internen Portal, wo Mitarbeiter Anmerkungen, Vorschläge und Ideen zur Dokumentation hinterlassen. Braucht der Support einen Artikel und gibt es den nicht? Hat der Tester eine Ungenauigkeit bemerkt? Hat ein Partner bei den Entwicklungsmanagern über Fehler geklagt? Alles in diese Gruppe! Die technischen Redakteure korrigieren sofort einige Dinge, übertragen andere in YouTrack oder nehmen sie sich zur Überlegung vor. Damit das Thema nicht verstummt, erinnern wir von Zeit zu Zeit an die Existenz der Gruppe und die Wichtigkeit von Feedback.

Problem 3. Der benötigte Artikel ist schwer zu finden

Ein Artikel, den man nicht finden kann, ist nichts besser als ein Artikel, der nicht existiert. Das Motto guter Dokumentation sollte der Satz „Leicht zu suchen, leicht zu finden“ sein. Wie erreicht man das?

Die Struktur ordnen und das Auswahlprinzip der Themen festlegen. Die Struktur sollte so transparent wie möglich sein, damit der Leser nicht denkt: „Wo kann ich diesen Artikel finden?“. Zusammengefasst gibt es zwei Ansätze: von der Benutzeroberfläche und von den Aufgaben.

1. Von der Benutzeroberfläche. Der Inhalt spiegelt die Abschnitte des Panels wider. So war es in der alten Dokumentation von ISPsystem.
2. Von den Aufgaben. Die Titel der Artikel und Abschnitte spiegeln die Aufgaben der Benutzer wider; in den Überschriften sind fast immer Verben und Antworten auf die Frage „Wie macht man es?“. Jetzt wechseln wir zu diesem Format.

Welchen Ansatz Sie auch wählen, stellen Sie sicher, dass das Thema den Anfragen der Benutzer entspricht und so behandelt wird, dass der Benutzer seine Frage eindeutig beantwortet bekommt.

Zentralisierte Suche einrichten. In einer idealen Welt sollte die Suche auch dann funktionieren, wenn man sich vertippt oder mit der Sprache falsch ist. Unsere Suche in Confluence kann dies bisher nicht bieten. Wenn Sie viele Produkte haben und die Dokumentation allgemein ist, passen Sie die Suche an die Seite an, auf der sich der Benutzer befindet. In unserem Fall funktioniert die Suche auf der Hauptseite für alle Produkte, während sie, wenn Sie sich bereits in einem bestimmten Abschnitt befinden, nur nach den Artikeln in diesem Bereich sucht.

Inhalt und „Breadcrumbs“ hinzufügen. Es ist von Vorteil, wenn auf jeder Seite ein Menü und Breadcrumbs vorhanden sind – der Weg des Benutzers zur aktuellen Seite mit der Möglichkeit, zu jeder Ebene zurückzukehren. In der alten Dokumentation von ISPsystem musste man den Artikel verlassen, um zum Inhalt zu gelangen. Das war unpraktisch, daher haben wir das in der neuen überarbeitet.

Links im Produkt anordnen. Wenn Menschen immer wieder mit derselben Frage den Support kontaktieren, ist es sinnvoll, einen Hinweis mit der Lösung in die Benutzeroberfläche einzufügen. Wenn Sie Daten oder Verständnis haben, wann der Benutzer auf ein Problem stößt, können Sie ihn auch per E-Mail benachrichtigen. So zeigen Sie Fürsorge und entlasten den Support.

Rechts im Popup-Fenster ist ein Link zum Artikel über die Einrichtung von DNSSEC im Bereich der Domainverwaltung von ISPmanager

Cross-Links innerhalb der Dokumentation einrichten. Artikel, die miteinander verbunden sind, sollten „verlinkt“ sein. Wenn die Artikel eine Folge darstellen, fügen Sie am Ende jedes Textes unbedingt Vor- und Zurückpfeile hinzu.

Wahrscheinlich wird eine Person zuerst nach einer Antwort auf ihre Frage nicht bei Ihnen, sondern bei einer Suchmaschine suchen. Es ist ärgerlich, wenn es aus technischen Gründen keine Links zur Dokumentation gibt. Sorgen Sie also für Suchmaschinenoptimierung.

Problem 4. Veraltetes Layout erschwert das Verständnis

Neben schlecht geschriebenen Texten kann das Design die Dokumentation verderben. Die Menschen sind es gewohnt, gut gestaltete Materialien zu lesen. Blogs, soziale Netzwerke, Medien – alle Inhalte werden nicht nur schön, sondern auch leicht lesbar und augenfreundlich präsentiert. Es ist daher leicht nachzuvollziehen, wie frustrierend es für eine Person ist, die einen Text sieht wie im Screenshot unten.

In diesem Artikel gibt es so viele Screenshots und Hervorhebungen, dass sie nicht helfen, sondern nur das Verständnis erschweren (das Bild ist anklickbar)

Es ist nicht ratsam, die Dokumentation zu einem Longread mit vielen Effekten zu machen, aber grundlegende Regeln sollten beachtet werden.

Layout. Bestimmen Sie die Breite des Haupttextes, die Schriftart, die Größe, die Überschriften und die Abstände. Ziehen Sie einen Designer hinzu, und um die Arbeit zu akzeptieren oder es selbst zu bewältigen, lesen Sie das Buch von Artem Gorbunov „Typografie und Layout“. Es bietet nur eine von vielen Perspektiven auf Layout, aber diese ist völlig ausreichend.

Hervorhebungen. Bestimmen Sie, was im Text hervorgehoben werden soll. Gewöhnlich handelt es sich um den Weg in der Benutzeroberfläche, Schaltflächen, Codeeinschlüsse, Konfigurationsdateien, „Achtung“-Blöcke. Legen Sie fest, wie diese Elemente hervorgehoben werden sollen, und halten Sie dies im Regelwerk fest. Beachten Sie, dass je weniger Hervorhebungen, desto besser. Wenn es zu viele gibt, wird der Text „lauter“. Selbst Anführungszeichen erzeugen Lärm, wenn sie zu häufig verwendet werden.

Screenshots. Vereinbaren Sie mit dem Team, in welchen Fällen Screenshots benötigt werden. Es ist nicht notwendig, jeden Schritt zu illustrieren. Eine große Anzahl von Screenshots, einschließlich einzelner Schaltflächen, erschwert das Verständnis und verschlechtert das Layout. Bestimmen Sie die Größe sowie das Format der Hervorhebungen und Bildunterschriften auf den Screenshots und halten Sie dies im Regelwerk fest. Denken Sie daran, dass Illustrationen immer dem Geschriebenen entsprechen und aktuell sein müssen. Wenn das Produkt regelmäßig aktualisiert wird, wird es schwierig sein, mit jedem Schritt Schritt zu halten.

Textlänge. Vermeiden Sie zu lange Artikel. Teilen Sie sie in Abschnitte auf, und wenn das nicht möglich ist, fügen Sie am Anfang des Artikels ein Inhaltsverzeichnis mit Ankerlinks hinzu. Eine einfache Möglichkeit, einen Artikel visuell kürzer zu machen, besteht darin, technische Details, die nur für einen engen Leserkreis erforderlich sind, unter einem Spoiler zu verbergen.

Formate. Kombinieren Sie in Artikeln mehrere Formate: Text, Video und Bilder. Das verbessert das Verständnis.

Versuchen Sie nicht, Probleme mit einer schönen Gestaltung zu überdecken. Ehrlich gesagt, wir haben selbst gehofft, dass die "Verpackung" die veraltete Dokumentation retten würde – das hat nicht funktioniert. In den Texten gab es so viel visuelles Rauschen und unnötige Details, dass die Richtlinien und das neue Design machtlos waren.

Vieles von dem, was oben beschrieben wurde, wird durch die Plattform bestimmt, die Sie für die Dokumentation verwenden. Bei uns ist das zum Beispiel Confluence. Auch damit mussten wir uns auseinandersetzen. Wenn es Sie interessiert, lesen Sie die Erzählung unseres Webentwicklers: Confluence für eine öffentliche Wissensdatenbank: Wir ändern das Design und konfigurieren die Sprachtrennung.

Womit Sie die Verbesserungen beginnen und wie Sie überleben

Wenn Ihre Dokumentation so umfangreich ist wie die von ISPsystem und Sie nicht wissen, wo Sie ansetzen sollen, beginnen Sie mit den ernsthaftesten Problemen. Die Kunden verstehen die Dokumentation nicht – kümmern Sie sich um die Verbesserung der Texte, erstellen Sie Richtlinien, schulen Sie die Autoren. Die Dokumentation ist veraltet – kümmern Sie sich um interne Prozesse. Beginnen Sie mit den beliebtesten Artikeln über die gefragtesten Produkte: Fragen Sie den Support, sehen Sie sich die Website-Analytik und die Suchanfragen an.

Um es gleich zu sagen – es wird nicht einfach werden. Und schnell wird es wahrscheinlich auch nicht gehen. Es sei denn, Sie fangen gerade erst an und machen alles gleich richtig. Eines wissen wir sicher – mit der Zeit wird es besser. Aber der Prozess wird niemals enden :-).

Quelle: habr.com