Die Softwaredokumentation ist nur eine Sammlung von Artikeln, aber selbst sie können Sie verrückt machen. Zuerst suchen Sie lange nach der richtigen Anweisung, dann verstehen Sie den obskuren Text, tun, was geschrieben steht, aber das Problem ist nicht gelöst. Sie suchen nach einem anderen Artikel, Sie sind nervös ... Nach einer Stunde spucken Sie auf alles und gehen. So funktioniert schlechte Dokumentation. Was macht es so und wie man es repariert - lesen Sie unter dem Schnitt.
Unsere alte Dokumentation hatte viele Mängel. Seit fast einem Jahr verarbeiten wir es so, dass das oben beschriebene Szenario unsere Kunden nicht betrifft. Sehen Sie, wie es war und wie es wurde .
Problem 1. Unverständliche, schlecht geschriebene Artikel
Wenn es unmöglich ist, die Dokumentation herauszufinden, worum geht es dann? Aber niemand schreibt absichtlich obskure Artikel. Sie werden erhalten, wenn der Autor nicht über das Publikum und den Zweck nachdenkt, Wasser einschenkt und den Text nicht auf Fehler überprüft.
- Das Publikum . Bevor Sie einen Artikel schreiben, müssen Sie über den Grad der Vorbereitung des Lesers nachdenken. Es ist logisch, dass Sie im Artikel für Anfänger die grundlegenden Schritte nicht überspringen und die Fachbegriffe ohne Entschlüsselung belassen sollten. Im Artikel über eine seltene Funktion, die nur für Profis erforderlich ist, sollten Sie die Bedeutung des Wortes PHP kennenlernen.
- Zweck . Eine andere Sache, über die Sie vorher nachdenken sollten. Der Autor sollte ein klares Ziel setzen, die nützliche Wirkung des Artikels bestimmen und entscheiden, was der Leser nach dem Lesen tun wird. Ist dies nicht der Fall, wird zur Beschreibung eine Beschreibung eingeholt.
- Wasser und Insekten . Viele unnötige Informationen und Klerikalismus, Fehler und Tippfehler beeinträchtigen die Wahrnehmung. Auch wenn der Leser keine Grammatiknation ist, kann ihn Nachlässigkeit im Text von sich stoßen.
Beachten Sie die obigen Tipps, und die Artikel werden klarer - garantiert. Um es noch besser zu machen,
stellen Sie sich bei der Arbeit an der technischen Dokumentation unseren
50 Fragen .
Problem 2. Artikel beantworten nicht alle Fragen
Es ist schlecht, wenn die Dokumentation nicht mit der Entwicklung Schritt hält, keine echten Fragen beantwortet und Fehler darin seit Jahren nicht mehr behoben wurden. Diese Probleme sind weniger der Autor als vielmehr die Organisation der Prozesse innerhalb des Unternehmens.
Die Dokumentation hält nicht mit der Entwicklung Schritt
Die Funktion ist bereits in der Version enthalten, Marketingpläne, um sie abzudecken, und es stellt sich heraus, dass der neue Artikel oder die neue Übersetzung immer noch nicht in der Dokumentation enthalten ist. Aus diesem Grund mussten wir die Veröffentlichung sogar verschieben. Sie können jeden bitten, die Aufgabe rechtzeitig an technische Redakteure zu übergeben, dies funktioniert jedoch nicht. Wenn der Prozess nicht automatisiert ist, wird die Situation wiederholt.
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 er beginnt, die Gelegenheit zu testen. Dann lernt das Marketing etwas über sie, um sich auf die Beförderung vorzubereiten. Benachrichtigungen sind auch im Corporate Messenger Mattermost enthalten, sodass es einfach unmöglich ist, Nachrichten von den Entwicklern zu verpassen.
Die Dokumentation spiegelt keine Benutzeranforderungen wider
Früher haben wir so gearbeitet: Ein Feature kam heraus, wir haben darüber gesprochen. Wir haben beschrieben, wie man es ein- und ausschaltet und feine Einstellungen vornimmt. Aber was ist, wenn der Kunde unsere Software auf eine Weise verwendet, die wir nicht erwartet hatten? Oder macht er Fehler, an die wir nicht gedacht haben?
Damit die Dokumentation so vollständig wie möglich ist, empfehlen wir Ihnen, Supportanfragen, Fragen in thematischen Foren und Fragen in Suchmaschinen zu analysieren. Die beliebtesten Themen sollten an technische Redakteure weitergegeben werden, um vorhandene Artikel zu ergänzen oder neue zu schreiben.
Die Dokumentation wird nicht verbessert
Es ist schwer, es sofort perfekt zu machen, trotzdem wird es Fehler geben. Sie können sich auf das Feedback von Kunden verlassen, aber es ist unwahrscheinlich, dass sie jeden Tippfehler, jede Ungenauigkeit, jeden unverständlichen oder unbekannten Artikel melden. Zusätzlich zu den Kunden lesen die Mitarbeiter die Dokumentation, was bedeutet, dass sie dieselben Fehler sehen. Es kann verwendet werden! Es müssen nur Bedingungen erstellt werden, unter denen ein Problem leicht gemeldet werden kann.
Wir haben eine Gruppe im internen Portal, in der Mitarbeiter Kommentare, Vorschläge und Ideen zur Dokumentation hinterlassen. Support braucht einen Artikel, aber nicht? Hat der Tester eine Ungenauigkeit festgestellt? Partner beschwerte sich bei Entwicklungsmanagern über Fehler? Alles in dieser Gruppe! Technische Redakteure reparieren sofort etwas, übertragen etwas auf YouTrack und nehmen sich etwas zum Nachdenken. Um das Thema ruhig zu halten, erinnern wir uns von Zeit zu Zeit an die Existenz der Gruppe und die Wichtigkeit von Feedback.
Problem 3. Sie müssen lange nach dem richtigen Artikel suchen
Ein Artikel, der nicht gefunden werden kann, ist nicht besser als ein Artikel, der nicht gefunden werden kann. Das Motto für eine gute Dokumentation sollte lauten: "Leicht zu suchen, leicht zu finden." Wie erreicht man das?
Optimieren Sie die Struktur und legen Sie das Prinzip der Themenauswahl fest . Die Struktur sollte so transparent wie möglich sein, damit der Leser nicht denkt: "Wo finde ich diesen Artikel?" Zusammenfassend gibt es zwei Ansätze: von der Schnittstelle und von Aufgaben.
- Von der Schnittstelle. Inhalt dupliziert Abschnitte des Bedienfelds. So war es in der alten ISPsystem-Dokumentation.
- Aus Aufgaben. Die Titel von Artikeln und Abschnitten spiegeln die Aufgaben der Benutzer wider. Überschriften enthalten fast immer Verben und Antworten auf die Frage „Wie geht das?“. Jetzt wechseln wir zu diesem Format.
Unabhängig davon, welchen Ansatz Sie wählen, stellen Sie sicher, dass das Thema den Anforderungen der Benutzer entspricht und behandelt wird, damit der Benutzer seine Frage genau löst.
Richten Sie eine zentralisierte Suche ein . In einer idealen Welt sollte die Suche auch dann funktionieren, wenn Sie traurig sind oder sich mit der Sprache irren. Unsere Suche in Confluence kann dies noch 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 Hauptsuche für alle Produkte, und wenn Sie sich bereits in einem bestimmten Abschnitt befinden, nur für die darin enthaltenen Artikel.
Fügen Sie Inhalt und Semmelbrösel hinzu . Es ist gut, wenn auf jeder Seite ein Menü und Brotkrumen vorhanden sind - der Pfad des Benutzers zur aktuellen Seite mit der Möglichkeit, zu einer beliebigen Ebene zurückzukehren. In der alten ISPsystem-Dokumentation mussten Sie den Artikel beenden, um in den Inhalt zu gelangen. Es war unpraktisch, also haben wir es im neuen behoben.
Ordnen Sie Links im Produkt an . Wenn von Zeit zu Zeit Leute mit derselben Frage zur Unterstützung kommen, ist es sinnvoll, der Benutzeroberfläche einen Hinweis mit ihrer Lösung hinzuzufügen. Wenn Sie Daten haben oder wissen, an welchem Punkt der Benutzer mit einem Problem konfrontiert ist, können Sie ihn auch per Newsletter benachrichtigen. Seien Sie vorsichtig und entfernen Sie die Last von der Stütze.
Rechts im Popup-Fenster befindet sich ein Link zu einem Artikel über die DNSSEC-Einrichtung im Abschnitt ISPmanager-DomänenverwaltungRichten Sie Querverweise in der Dokumentation ein . Verwandte Artikel sollten „verlinkt“ sein. Wenn es sich bei den Artikeln um eine Sequenz handelt, müssen Sie am Ende jedes Textes Vorwärts- und Rückwärtspfeile einfügen.
Höchstwahrscheinlich wird eine Person zuerst nach einer Antwort auf ihre Frage suchen, nicht an Sie, sondern an eine Suchmaschine. Es ist eine Schande, wenn es aus technischen Gründen keine Links zur Dokumentation gibt. Kümmere dich also um die Suchmaschinenoptimierung.
Problem 4. Veraltetes Layout beeinträchtigt die Wahrnehmung
Zusätzlich zu schlechten Texten kann das Design die Dokumentation ruinieren. Die Leute sind es gewohnt, gut gemachte Materialien zu lesen. Blogs, soziale Netzwerke, Medien - alle Inhalte werden nicht nur schön präsentiert, sondern sind auch leicht zu lesen und angenehm für das Auge. Daher können Sie den Schmerz einer Person, die den Text wie im folgenden Screenshot sieht, leicht verstehen.
Es gibt so viele Screenshots und Auswahlen in diesem Artikel, dass sie nicht helfen, sondern nur die Wahrnehmung beeinträchtigen (das Bild ist anklickbar).Es lohnt sich nicht, ein Longrid mit einer Reihe von Effekten aus der Dokumentation zu erstellen, aber Sie müssen die Grundregeln berücksichtigen.
Layout . Definieren Sie die Breite des Haupttextes, die Schriftart, die Größe, die Überschriften und die Einrückungen. Beauftragen Sie einen Designer, und lesen Sie Artyom Gorbunovs Buch Typografie und Layout, um einen Job anzunehmen oder selbst zu erledigen. Es wird nur eine der Ansichten des Layouts angezeigt, aber es reicht völlig aus.
Zuweisungen . Definieren Sie, was im Text hervorgehoben werden muss. Normalerweise ist dies der Pfad in der Benutzeroberfläche, den Schaltflächen, Codeeinfügungen, Konfigurationsdateien und den Blöcken „Achtung“. Legen Sie die Auswahl dieser Elemente fest und legen Sie sie im Zeitplan fest. Denken Sie daran, dass je weniger Ausscheidung, desto besser. Wenn es viele davon gibt, macht der Text „Lärm“. Selbst Anführungszeichen verursachen Rauschen, wenn sie zu oft verwendet werden.
Screenshots Vereinbaren Sie mit dem Team, in welchen Fällen Screenshots benötigt werden. Es ist definitiv nicht notwendig, jeden Schritt zu veranschaulichen. Eine große Anzahl von Screenshots, einschließlich einzelne Tasten beeinträchtigen die Wahrnehmung und verderben das Layout. Bestimmen Sie die Größe sowie das Format der Auswahl und Beschriftungen in den Screenshots, die in den Vorschriften festgelegt sind. Denken Sie daran, dass Abbildungen immer geschrieben und relevant sein müssen. Wenn das Produkt regelmäßig aktualisiert wird, ist es wiederum schwierig, den Überblick zu behalten.
Die Länge des Textes . Vermeiden Sie zu lange Artikel. Fragmentieren Sie sie in Teile und fügen Sie, falls nicht möglich, ankerverknüpften Inhalt oben im Artikel hinzu. Eine einfache Möglichkeit, einen Artikel optisch kürzer zu gestalten, besteht darin, die technischen Details, die ein enger Leserkreis benötigt, unter einem Spoiler zu verbergen.
Formate Kombinieren Sie verschiedene Formate in Artikeln: Text, Video und Bilder. Dies wird die Wahrnehmung verbessern.
Versuchen Sie nicht, Probleme mit einem schönen Layout zu vertuschen. Ehrlich gesagt hofften wir selbst, dass der "Wrapper" die veraltete Dokumentation speichern würde - es hat nicht geklappt. Die Texte hatten so viel visuelles Rauschen und unnötige Details, dass die Vorschriften und das neue Design machtlos waren.
Ein Großteil der oben genannten Punkte wird von der Site bestimmt, die Sie für die Dokumentation verwenden. Für uns ist das zum Beispiel Confluence. Er musste auch basteln. Lesen Sie bei Interesse die Geschichte unseres Webentwicklers:
Zusammenfluss für eine öffentliche Wissensbasis: Ändern Sie das Design und richten Sie die Sprachentrennung ein .
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, was Sie abrufen sollen, beginnen Sie mit den schwerwiegendsten Problemen. Kunden verstehen es nicht, Texte zu verbessern, Vorschriften zu erlassen und Schriftsteller auszubilden. Die Dokumentation ist veraltet - übernehmen Sie interne Prozesse. Beginnen Sie mit den beliebtesten Artikeln zu den gefragtesten Produkten: Bitten Sie um Unterstützung, lesen Sie Website-Analysen und Suchmaschinenabfragen.
Sagen wir gleich - es wird nicht einfach. Und auch schnell ist es unwahrscheinlich, dass es gelingt. Es sei denn, Sie fangen gerade erst an und tun es sofort. Wir wissen eines ganz genau: Mit der Zeit wird es besser. Aber der Prozess wird niemals enden :-).