Softwaredokumentation besteht lediglich aus einer Reihe von Artikeln. Aber auch sie können einen in den Wahnsinn treiben. Zunächst sucht man lange nach der nötigen Anleitung. Dann verstehen Sie den unklaren Text. Sie machen wie beschrieben, aber das Problem ist nicht gelöst. Du suchst nach einem weiteren Artikel, wirst nervös ... Eine Stunde später gibst du alles auf und gehst. So funktioniert schlechte Dokumentation. Warum das so ist und wie man es behebt – lesen Sie unter dem Schnitt.
In unserer alten Dokumentation gab es viele Mängel. Damit sich das oben beschriebene Szenario nicht auf unsere Kunden auswirkt, arbeiten wir seit fast einem Jahr daran. Sehen, и .
Problem 1: Unklare, schlecht geschriebene Artikel
Wenn die Dokumentation nicht verständlich ist, welchen Sinn hat sie dann? Aber niemand schreibt absichtlich unverständliche Artikel. Sie passieren, wenn der Autor nicht an die Zielgruppe und den Zweck denkt, Wasser gießt und den Text nicht auf Fehler überprüft.
- Publikum. Bevor Sie einen Artikel schreiben, müssen Sie über den Vorbereitungsstand des Lesers nachdenken. Es ist logisch, dass Sie in einem Artikel für Anfänger nicht die grundlegenden Schritte überspringen und Fachbegriffe ohne Erklärung lassen sollten, aber in einem Artikel über eine seltene Funktion, die nur Profis benötigen, sollten Sie die Bedeutung des Wortes PHP erklären.
- Ziel. Noch etwas, worüber man im Vorfeld nachdenken sollte. Der Autor muss ein klares Ziel festlegen, die nützliche Wirkung des Artikels bestimmen und entscheiden, was der Leser nach der Lektüre tun wird. Geschieht dies nicht, erhalten Sie am Ende eine Beschreibung um der Beschreibung willen.
- Wasser und Insekten. Es gibt viele unnötige Informationen und Bürokratie, Fehler und Tippfehler beeinträchtigen die Wahrnehmung. Selbst wenn der Leser kein Grammatik-Nazi ist, kann ihn eine Nachlässigkeit im Text abschrecken.
Beachten Sie die oben genannten Tipps und die Artikel werden garantiert klarer. Um es noch besser zu machen, nutzen Sie unsere .
Problem 2. Artikel beantworten nicht alle Fragen
Es ist schlimm, wenn die Dokumentation nicht mit der Entwicklung Schritt hält, keine echten Fragen beantwortet und Fehler darin jahrelang nicht korrigiert werden. Dabei handelt es sich nicht so sehr um Probleme des Autors, sondern um die Organisation von Prozessen im Unternehmen.
Die Dokumentation hält nicht mit der Entwicklung Schritt
Die Funktion ist bereits in der Veröffentlichung, das Marketing plant, darüber zu berichten, und dann stellt sich heraus, dass der neue Artikel oder die neue Übersetzung noch nicht in der Dokumentation enthalten ist. Aus diesem Grund mussten wir die Veröffentlichung sogar verschieben. Sie können jeden bitten, Aufgaben so oft Sie möchten, pünktlich an technische Redakteure zu übergeben, aber das wird nicht funktionieren. Wenn der Prozess nicht automatisiert ist, wird sich die Situation wiederholen.
Wir haben Änderungen an YouTrack vorgenommen. Die Aufgabe, einen Artikel über eine neue Funktion zu schreiben, fällt dem technischen Redakteur in dem Moment zu, in dem mit dem Testen der Funktion begonnen wird. Dann erfährt das Marketing davon, um sich auf die Promotion vorzubereiten. Benachrichtigungen kommen auch an den Unternehmens-Messenger Mattermost, sodass es einfach unmöglich ist, Neuigkeiten von Entwicklern zu verpassen.
Die Dokumentation spiegelt keine Benutzerwünsche wider
Wir sind es gewohnt, so zu arbeiten: Ein Feature kam heraus, wir haben darüber gesprochen. Wir haben beschrieben, wie man es ein- und ausschaltet und Feineinstellungen vornimmt. Was aber, wenn ein Kunde unsere Software auf eine Weise nutzt, die wir nicht erwartet haben? Oder enthält es Fehler, über die wir nicht nachgedacht haben?
Um eine möglichst vollständige Dokumentation sicherzustellen, empfehlen wir die Analyse von Supportanfragen, Fragen in Themenforen und Suchanfragen in Suchmaschinen. Die beliebtesten Themen werden an Technische Redakteure übertragen, damit diese bestehende Artikel ergänzen oder neue schreiben können.
Die Dokumentation wird nicht verbessert
Es ist schwierig, es sofort perfekt zu machen; es wird immer noch Fehler geben. Sie können auf Feedback von Kunden hoffen, aber es ist unwahrscheinlich, dass sie jeden Tippfehler, jede Ungenauigkeit, jeden unverständlichen oder nicht gefundenen Artikel melden. Neben Kunden lesen auch Mitarbeiter die Dokumentation, was bedeutet, dass ihnen dieselben Fehler auffallen. Das kann man nutzen! Sie müssen lediglich Bedingungen schaffen, unter denen es einfach ist, ein Problem zu melden.
Auf dem internen Portal haben wir eine Gruppe, in der Mitarbeiter Kommentare, Vorschläge und Ideen zur Dokumentation hinterlassen. Benötigt der Support einen Artikel, der aber nicht existiert? Ist dem Tester die Ungenauigkeit aufgefallen? Hat sich der Partner bei den Entwicklungsleitern über Fehler beschwert? Alle in dieser Gruppe! Technische Redakteure beheben einige Dinge sofort, übertragen einige Dinge auf YouTrack und geben anderen etwas Zeit zum Nachdenken. Damit das Thema nicht verstummt, erinnern wir Sie von Zeit zu Zeit an die Existenz der Gruppe und die Bedeutung von Feedback.
Problem 3. Es dauert lange, den richtigen Artikel zu finden.
Ein Artikel, der nicht gefunden werden kann, ist nicht besser als ein Artikel, der nicht gefunden werden kann. Das Motto einer guten Dokumentation sollte lauten: „Leicht zu suchen, leicht zu finden.“ Wie erreicht man das?
Organisieren Sie die Struktur und legen Sie das Prinzip für die Themenauswahl fest. Der Aufbau sollte möglichst transparent sein, damit der Leser nicht denkt: „Wo finde ich diesen Artikel?“ Zusammenfassend gibt es zwei Ansätze: von der Schnittstelle und von den Aufgaben.
- Von der Schnittstelle. Der Inhalt dupliziert die Panelabschnitte. Dies war in der alten ISPsystem-Dokumentation der Fall.
- Von Aufgaben. Die Titel von Artikeln und Abschnitten spiegeln die Aufgaben der Benutzer wider; Titel enthalten fast immer Verben und Antworten auf die „Wie“-Frage. Jetzt wechseln wir zu diesem Format.
Welchen Ansatz Sie auch wählen, stellen Sie sicher, dass das Thema für die Suche der Benutzer relevant ist und auf eine Art und Weise behandelt wird, die speziell auf die Frage des Benutzers eingeht.
Richten Sie eine zentrale Suche ein. Im Idealfall sollte die Suche auch dann funktionieren, wenn Sie sich falsch buchstabieren oder einen Sprachfehler machen. Unsere bisherige Suche in Confluence kann uns damit nicht gefallen. 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, und wenn Sie sich bereits in einer bestimmten Rubrik befinden, dann nur für die darin enthaltenen Artikel.
Inhalt und Semmelbrösel hinzufügen. Es ist gut, wenn jede Seite ein Menü und Breadcrumbs hat – den Pfad des Benutzers zur aktuellen Seite mit der Möglichkeit, zu jeder Ebene zurückzukehren. In der alten ISPsystem-Dokumentation musste man den Artikel verlassen, um zum Inhalt zu gelangen. Es war unpraktisch, also haben wir es im neuen behoben.
Platzieren Sie Links im Produkt. Wenn Leute immer wieder mit der gleichen Frage zum Support kommen, ist es sinnvoll, der Schnittstelle einen Hinweis mit der Lösung hinzuzufügen. Wenn Sie Daten oder Erkenntnisse darüber haben, wann bei einem Benutzer ein Problem auftritt, können Sie ihn auch über eine Mailingliste benachrichtigen. Zeigen Sie ihnen Anteilnahme und entlasten Sie sie von der Unterstützung.
Rechts im Popup-Fenster befindet sich ein Link zu einem Artikel über die Einrichtung von DNSSEC im Domänenverwaltungsbereich von ISPmanager
Richten Sie Querverweise innerhalb der Dokumentation ein. Artikel, die miteinander in Zusammenhang stehen, sollten „verlinkt“ werden. Wenn die Artikel sequentiell sind, achten Sie darauf, am Ende jedes Textes Vorwärts- und Rückwärtspfeile einzufügen.
Höchstwahrscheinlich wird eine Person zunächst nicht bei Ihnen, sondern bei einer Suchmaschine nach einer Antwort auf ihre Frage suchen. Schade, wenn dort aus technischen Gründen keine Links zur Dokumentation vorhanden sind. Kümmern Sie sich also um die Suchmaschinenoptimierung.
Problem 4. Veraltetes Layout beeinträchtigt die Wahrnehmung
Zusätzlich zu schlechten Texten kann auch die Dokumentation durch Design beeinträchtigt werden. Menschen sind es gewohnt, gut geschriebene Materialien zu lesen. Blogs, soziale Netzwerke, Medien – alle Inhalte werden nicht nur schön präsentiert, sondern auch gut lesbar und optisch ansprechend. Daher können Sie den Schmerz einer Person, die Text wie im folgenden Screenshot sieht, leicht verstehen.
Es gibt so viele Screenshots und Highlights in diesem Artikel, dass sie nicht weiterhelfen, sondern nur die Wahrnehmung stören (das Bild ist anklickbar)
Sie sollten die Dokumentation mit einer Reihe von Effekten nicht lange durchlesen, aber Sie müssen die Grundregeln berücksichtigen.
Layout. Bestimmen Sie die Breite, Schriftart, Größe, Überschriften und Abstände des Textkörpers. Beauftragen Sie einen Designer und lesen Sie Artyom Gorbunovs Buch „Typografie und Layout“, um die Arbeit anzunehmen oder selbst zu erledigen. Es stellt zwar nur eine Ansicht des Layouts dar, reicht aber vollkommen aus.
Zuteilung. Bestimmen Sie, was im Text hervorgehoben werden muss. Typischerweise handelt es sich hierbei um einen Pfad in der Benutzeroberfläche, Schaltflächen, Codeeinfügungen, Konfigurationsdateien und „Bitte beachten“-Blöcke. Bestimmen Sie die Zuteilung dieser Elemente und halten Sie sie in den Vorschriften fest. Bedenken Sie: Je weniger Ausfluss, desto besser. Wenn es viele davon gibt, ist der Text verrauscht. Selbst Anführungszeichen erzeugen Lärm, wenn sie zu oft verwendet werden.
Screenshots. Vereinbaren Sie mit dem Team, in welchen Fällen Screenshots erforderlich sind. Es ist definitiv nicht nötig, jeden Schritt zu veranschaulichen. Zahlreiche Screenshots, inkl. separate Tasten, stören die Wahrnehmung, verderben das Layout. Bestimmen Sie die Größe sowie das Format der Hervorhebungen und Signaturen auf Screenshots und halten Sie diese in den Vorschriften fest. Denken Sie daran, dass Illustrationen immer dem Geschriebenen entsprechen und relevant sein sollten. Auch hier gilt: Wenn das Produkt regelmäßig aktualisiert wird, wird es schwierig sein, den Überblick über alle zu behalten.
Textlänge. Vermeiden Sie zu lange Artikel. Teilen Sie sie in Teile auf, und wenn dies nicht möglich ist, fügen Sie Inhalte mit Ankerlinks am Anfang des Artikels hinzu. Eine einfache Möglichkeit, einen Artikel optisch kürzer zu machen, besteht darin, technische Details, die für einen engen Leserkreis benötigt werden, unter einem Spoiler zu verbergen.
Formate. Kombinieren Sie in Ihren Artikeln mehrere Formate: Text, Video und Bilder. Dadurch wird die Wahrnehmung verbessert.
Versuchen Sie nicht, Probleme durch ein schönes Layout zu vertuschen. Ehrlich gesagt haben wir selbst gehofft, dass der „Wrapper“ die veraltete Dokumentation retten würde – das hat nicht geklappt. Die Texte enthielten so viel visuelles Rauschen und unnötige Details, dass die Vorschriften und das neue Design machtlos waren.
Ein Großteil der oben genannten Punkte hängt von der Plattform ab, die Sie für die Dokumentation verwenden. Wir haben zum Beispiel Confluence. Ich musste auch an ihm herumbasteln. Bei Interesse lesen Sie die Geschichte unseres Webentwicklers: .
Wo man anfangen kann, sich zu verbessern und wie man überlebt
Wenn Ihre Dokumentation so umfangreich ist wie die von ISPsystem und Sie nicht wissen, wo Sie anfangen sollen, beginnen Sie mit den größten Problemen. Kunden verstehen das Dokument nicht – verbessern Sie die Texte, machen Sie Vorschriften, schulen Sie Autoren. Dokumentation ist veraltet – kümmern Sie sich um interne Prozesse. Beginnen Sie mit den beliebtesten Artikeln zu den beliebtesten Produkten: Fragen Sie den Support, sehen Sie sich Website-Analysen und Suchanfragen in Suchmaschinen an.
Sagen wir gleich: Es wird nicht einfach. Und es ist auch unwahrscheinlich, dass es schnell klappt. Es sei denn, Sie fangen gerade erst an und tun sofort das Richtige. Wir wissen mit Sicherheit, dass es mit der Zeit besser wird. Aber der Prozess wird nie enden :-).
Source: habr.com