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

Dokumentation zu Software ist einfach eine Ansammlung von Artikeln. Aber selbst diese können frustrieren. Zuerst sucht man lange nach der richtigen Anleitung. Dann kämpft man mit unverständlichem Text. Man macht, was geschrieben steht, aber 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 das ändern kann – lesen Sie unten.

In unserer alten Dokumentation gab es viele Mängel. Seit fast einem Jahr überarbeiten wir sie, um sicherzustellen, dass das oben beschriebene Szenario unsere Kunden nicht betrifft. Sehen Sie sich an, wie es war und wie es jetzt ist.

Problem 1. Unklare, schlecht geschriebene Artikel

Wenn man in der Dokumentation nicht klar kommt, was hat sie dann für einen Sinn? Aber niemand schreibt absichtlich unklare Artikel. Diese entstehen, wenn der Autor nicht an das Publikum und das Ziel denkt, unnötiges Gerede ausbreitet und den Text nicht auf Fehler überprüft.

• Das Publikum. Vor dem Schreiben eines Artikels sollte man über das Wissensniveau des Lesers nachdenken. Es ist logisch, dass in einem Artikel für Anfänger die grundlegenden Schritte nicht ausgelassen und technische Begriffe ohne Erläuterung stehen gelassen werden sollten, während in einem Artikel über eine seltene Funktion, die nur für Profis relevant ist, die Bedeutung des Begriffs PHP erklärt werden sollte.
• Ziel. Eine weitere Sache, über die man im Voraus nachdenken sollte. Der Autor sollte ein klares Ziel setzen, die nützliche Handlung des Artikels definieren und entscheiden, was der Leser nach dem Lesen tun wird. Andernfalls entsteht eine Beschreibung nur um der Beschreibung willen.
• Wasser und Fehler. Zu viele überflüssige Informationen und Bürokratismen, Fehler und Tippfehler stören das Verständnis. Selbst wenn der Leser kein Grammatik-Nazi ist, kann Nachlässigkeit im Text ihn abschrecken.

Berücksichtigen Sie die oben genannten Tipps, und die Artikel werden garantiert verständlicher. Um es noch besser zu machen, nehmen Sie unsere 50 Fragen zur Erstellung technischer Dokumentationen zur Hand.

Problem 2. Artikel beantworten nicht alle Fragen

Es ist schlecht, wenn die Dokumentation mit der Entwicklung nicht Schritt hält, reale Fragen nicht beantwortet werden und Fehler über Jahre hinweg nicht korrigiert werden. Das sind weniger Probleme des Autors, sondern vielmehr der Organisation der Prozesse innerhalb des Unternehmens.

Die Dokumentation hält nicht mit der Entwicklung Schritt

Das Feature ist bereits veröffentlicht, das Marketing plant, es zu bewerben, und nun stellt sich heraus, dass es noch keinen Artikel oder Übersetzung in der Dokumentation gibt. Das hat uns sogar gezwungen, die Veröffentlichung zu verschieben. Man kann so oft wie nötig alle auffordern, die Aufgaben rechtzeitig an die technischen Redakteure weiterzuleiten, 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 das neue Feature fällt gleichzeitig mit dem Beginn der Tests an einen technischen Redakteur. Auch das Marketing erfährt dann davon, um sich auf die Promotion vorzubereiten. Die Benachrichtigungen kommen zudem in den Unternehmensmessenger Mattermost, sodass es unmöglich ist, Neuigkeiten von den Entwicklern zu verpassen.

Die Dokumentation spiegelt nicht die Anfragen der Nutzer wider.

Wir sind es gewohnt, so zu arbeiten: Ein Feature wird veröffentlicht, und wir berichten darüber. Wir beschreiben, wie man es ein- und ausschaltet sowie feine Anpassungen vornimmt. Aber was ist, wenn der Kunde unsere Software anders anwendet, als wir angenommen haben? Oder wenn Fehler auftreten, an die wir nicht gedacht haben?

Um die Dokumentation so vollständig wie möglich zu gestalten, empfehlen wir die Analyse von Support-Anfragen, Fragen in themenspezifischen Foren und Suchanfragen. Die populärsten Themen sollten an technische Autoren weitergeleitet werden, damit sie bestehende Artikel ergänzen oder neue schreiben.

Die Dokumentation wird nicht verbessert

Es ist schwierig, sofort etwas Perfektes zu schaffen, Fehler werden immer auftreten. Man kann auf Feedback von Kunden hoffen, aber es ist unwahrscheinlich, dass sie über jeden Tippfehler, Ungenauigkeiten oder unklare bzw. nicht gefundene Artikel berichten. Neben den Kunden lesen auch Mitarbeiter die Dokumentation, das heißt, sie sehen die gleichen Fehler. Das kann genutzt werden! Es müssen nur Bedingungen geschaffen werden, unter denen es einfach ist, ein Problem zu melden.

Wir haben eine Gruppe im internen Portal, in der Mitarbeiter Anmerkungen, Vorschläge und Ideen zur Dokumentation hinterlassen. Braucht der Support einen Artikel, der nicht existiert? Hat der Tester eine Ungenauigkeit bemerkt? Hat ein Partner den Entwicklungsmanagern Fehler gemeldet? All dies gehört in diese Gruppe! Technische Redakteure korrigieren sofort manche Dinge, übertragen andere in YouTrack und nehmen einige zur Überlegung mit. Damit das Thema nicht verstummt, erinnern wir von Zeit zu Zeit an die Existenz der Gruppe und die Wichtigkeit des Feedbacks.

Problem 3. Der gesuchte Artikel ist schwer zu finden.

Ein Artikel, der nicht gefunden werden kann, ist nicht besser als ein nicht existierender Artikel. Das Motto guter Dokumentation sollte lauten: „Einfach suchen, einfach finden“. Wie erreicht man das?

Die Struktur ordnen und das Kriterium für die Themenauswahl festlegen.Die Struktur muss so transparent wie möglich sein, damit der Leser sich nicht fragt: "Wo finde ich diesen Artikel?" Zusammenfassend 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. Aufgaben. Die Titel von Artikeln und Abschnitten spiegeln die Anliegen der Benutzer wider; in den Überschriften gibt es fast immer Verben und Antworten auf die Frage „Wie macht man es?“. Jetzt wechseln wir zu diesem Format.

Egal, welchen Ansatz Sie wählen, stellen Sie sicher, dass das Thema den Benutzeranfragen entspricht und so behandelt wird, dass der Benutzer seine Fragen eindeutig beantworten kann.

Zentralisierte Suche einrichten. In einer idealen Welt sollte die Suche auch dann funktionieren, wenn man sich vertippt oder mit der Sprache einen Fehler macht. Unsere Suche in Confluence kann das derzeit noch 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 in einem bestimmten Abschnitt nur für die Artikel in diesem Abschnitt funktioniert.

Inhaltsverzeichnis und „Breadcrumbs“ hinzufügen. Es ist vorteilhaft, wenn jede Seite ein Menü und Breadcrumbs hat – der Weg des Benutzers zur aktuellen Seite mit der Möglichkeit, auf jede Ebene zurückzukehren. In der alten ISPsystem-Dokumentation musste man den Artikel verlassen, um zum Inhaltsverzeichnis zu gelangen. Das war unpraktisch, daher haben wir das in der neuen Version geändert.

Links im Produkt anordnen. Wenn Menschen immer wieder mit der gleichen Frage den Support kontaktieren, ist es sinnvoll, einen Hinweis mit der Lösung im Interface hinzuzufügen. Wenn Sie Daten oder ein Verständnis dafür haben, wann der Benutzer auf ein Problem stößt, können Sie ihn auch per Newsletter informieren. So zeigen Sie Fürsorge und entlasten den Support.

Auf der rechten Seite im Popup-Fenster befindet sich ein Link zu dem Artikel über die Einstellung von DNSSEC im Abschnitt zur Verwaltung von Domains in ISPmanager.

Cross-Links innerhalb der Dokumentation einrichten.. Artikel, die miteinander verbunden sind, sollten "verlinkt" werden. Wenn Artikel eine Reihenfolge darstellen, fügen Sie am Ende jedes Textes unbedingt Vorwärts- und Rückwärtspfeile hinzu.

Wahrscheinlich wird jemand zuerst die Antwort auf seine Frage nicht bei Ihnen, sondern in einer Suchmaschine suchen. Es wäre ärgerlich, wenn aus technischen Gründen keine Links zur Dokumentation vorhanden sind. Achten Sie also auf Suchmaschinenoptimierung.

Problem 4. Veraltete Layouts beeinträchtigen das Verständnis.

Neben schlechten Texten kann das Design die Dokumentation verderben. Menschen sind es gewohnt, gut gestaltete Materialien zu lesen. Blogs, soziale Medien, und andere Inhalte werden nicht nur schön, sondern auch lesefreundlich und angenehm für die Augen präsentiert. Daher ist es leicht nachzuvollziehen, welchen Schmerz jemand empfindet, der einen Text sieht, wie im Screenshot unten.

In diesem Artikel gibt es so viele Screenshots und Hervorhebungen, dass sie nicht hilfreich sind, sondern nur die Wahrnehmung stören (Bild ist anklickbar).

Man sollte aus der Dokumentation keinen Longread mit vielen Effekten machen, aber grundlegende Regeln müssen berücksichtigt werden.

Gestaltung. 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 erledigen, lesen Sie das Buch von Artem Gorbunov «Typografie und Gestaltung». Es bietet nur einen Ansatz zur Gestaltung, aber dieser ist völlig ausreichend.

Hervorhebungen. Bestimmen Sie, welche Textstellen hervorgehoben werden müssen. Dies betrifft in der Regel Wege im Interface, Schaltflächen, Codeeinfügungen, Konfigurationsdateien und Hinweise. Legen Sie fest, wie diese Elemente hervorgehoben werden sollen, und halten Sie dies in den Richtlinien fest. Bedenken Sie, dass weniger Hervorhebungen besser sind. Wenn es zu viele gibt, wird der Text "laut". Auch Anführungszeichen können ein Geräusch erzeugen, wenn sie zu häufig verwendet werden.

Screenshots. Klären Sie mit dem Team, in welchen Fällen Screenshots erforderlich sind. Es ist nicht notwendig, jeden Schritt zu illustrieren. Eine große Anzahl von Screenshots, einschließlich einzelner Schaltflächen, beeinträchtigt das Verständnis und stört das Layout. Bestimmen Sie Größe und Format der Hervorhebungen sowie der Beschriftungen auf den Screenshots, und halten Sie dies in den Richtlinien fest. Denken Sie daran, dass Illustrationen immer dem Geschriebenen entsprechen und aktuell sein sollten. Nochmals, wenn das Produkt regelmäßig aktualisiert wird, wird es schwierig sein, alles im Auge zu behalten.

Länge des Textes. Vermeiden Sie übermäßig 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 gestalten, besteht darin, technische Details, die nur für einen kleinen Leserkreis von Interesse sind, unter einem Spoiler zu verstecken.

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

Versuchen Sie nicht, Probleme mit einer ansprechenden Gestaltung zu verbergen. Ehrlich gesagt, wir haben selbst gehofft, dass die 'Hülle' die veraltete Dokumentation retten würde – das hat nicht geklappt. In den Texten gab es so viel visuelles Rauschen und überflüssige Details, dass die Richtlinien und das neue Design machtlos waren.

Vieles von dem, was oben beschrieben wurde, hängt von der Plattform ab, die Sie für die Dokumentation verwenden. Bei uns ist das zum Beispiel Confluence. Auch damit mussten wir viel arbeiten. Wenn es Sie interessiert, lesen Sie die Erzählung unseres Webentwicklers: Confluence für eine öffentliche Wissensdatenbank: Designänderung und Anpassung der Sprachtrennung.

Wie man mit Verbesserungen beginnt und überlebt

Wenn Ihre Dokumentation so umfangreich ist wie die von ISPsystem und Sie nicht wissen, wo Sie anfangen sollen, beginnen Sie mit den dringendsten Problemen. Kunden verstehen die Dokumentation nicht – verbessern Sie die Texte, erstellen Sie Richtlinien, schulen Sie die Autoren. Die Dokumentation ist veraltet – arbeiten Sie an den internen Prozessen. Beginnen Sie mit den beliebtesten Artikeln über die meistgefragten Produkte: Fragen Sie den Support, schauen Sie sich die Website-Analyse und Suchanfragen an.

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

Quelle: habr.com