Im Herbst 2016 wurden mein Kollege und ich angewiesen, die Dokumentation und den Inhalt meines früheren Unternehmens zu verbessern. Wir haben ein Jahr mit allen Arten von Dokumentation verbracht: API-Referenzen, Anleitungen, Tutorials, Blog-Beiträge. Vorher habe ich 5 Jahre lang Docks geschrieben, aber das habe ich offiziell nicht gelernt. Aber ich kann nicht als unerfahren bezeichnet werden: Neben der Dokumentation der API für Projekte und Startups unterrichtete ich Python Flask auch in Seminaren, während ich in den letzten Kursen an der Universität studierte. Jetzt ist es eine Gelegenheit, sich nur auf mein Lieblingsgeschäft zu konzentrieren: Spezialisten auf allen Ebenen durch technische Dokumentation zu helfen.

Dieses Jahr habe ich viel von der Write The Docs-Community, von anderen API-Anbietern und der Trial-and-Error-Methode gelernt. Letztes Jahr teilte ich meine Erfahrungen in dem Bericht „Was ich über das Schreiben von Dokumentation wissen möchte“ auf der Portland API Strategy and Practice Conference mit. Dieser Artikel gibt einen Überblick über die gewonnenen Erkenntnisse.

Wie lesen die Leute die Dokumentation tatsächlich?

"Eine Nation schaudert bei einem großen Fragment eines einzelnen Textes", Foto von The Onion

Kennst du dieses Gefühl wie auf dem Bild? Es passiert. Vielleicht nicht physisch, aber höchstwahrscheinlich schaudern die Menschen mental. Ich wurde ständig von dem Gedanken gequält, dass die Leute meine Texte nicht lesen würden, wenn ich sie nicht auf leicht verdauliche Weise ausmachen würde. Meine Güte, das kann sogar mit diesem Artikel passieren.

In einer Nachschlagestudie der Neilson Norman Group aus dem Jahr 2006 haben 232 Benutzer Tausende von Webseiten angesehen. Es stellte sich heraus, dass Benutzer Seiten normalerweise mit dem F-Muster betrachten:

„Zuerst lesen sie in horizontaler Richtung , normalerweise im oberen Teil des Inhaltsbereichs. Dies ist das oberste Element der Figur F. “
„Dann bewegen sie sich ein wenig nach unten - und machen eine zweite horizontale Bewegung, die normalerweise einen kürzeren Bereich als die vorherige abdeckt. Dieses zusätzliche Element bildet das mittlere Element der Figur F ".
„Schließlich scannen Benutzer die linke Seite des Inhalts vertikal . Manchmal ist dies ein langsamer und systematischer Scan, der als fester Streifen auf einer Heatmap angezeigt wird. Manchmal ist die Bewegung schneller und bildet Flecken auf der Heatmap. Dies ist das letzte vertikale Element in der Figur F. "

Heatmaps Nielsen Norman Group

Die Studie fand einige alternative Scanmuster, wie z. B. ein Puff-Cake-Muster, eine fleckige Karte, eine Layout-Vorlage, ein Bypass-Muster und ein zweckmäßiges Muster. Ich empfehle Ihnen dringend, den Bericht zu lesen.

Es ist wichtig zu beachten, dass das F-Muster den Benutzern im Weg steht , aber eine gute Positionierung des Inhalts hilft, F-Scans zu verhindern.

Was sind die spezifischen Auswirkungen auf die Dokumentation?

Die ersten beiden Absätze sollten die wichtigsten Informationen enthalten.
Die ersten 3-5 Wörter sind kritisch
Überschriften, Absätze und Listen mit Aufzählungszeichen mit informativen Wörtern
Änderungen der Schriftart (Größe, Links, Fettdruck usw.) können erforderlich sein, um die Aufmerksamkeit des Lesers zu erhalten

Wie strukturiere ich den Inhalt der Seite?

Scannen verhindern: Stellen Sie sicher, dass die Informationen, die der Leser benötigt, hervorgehoben sind
Ein Gedanke zu einem Absatz. Wenn es mehrere gibt, brechen Sie den Absatz
Benutzer überspringen alles, was wie Banner aussieht. Seien Sie also vorsichtig mit den Abbildungen.
Erweitern Sie die Textspalte nicht zu stark: optimalerweise 65–90 Zeichen

Einige dieser Tipps habe ich aus Kevin Burkes Vortrag "Wie man eine Dokumentation für Benutzer schreibt, die sie nicht lesen" gelernt. Kevin unterstützte die Twilio-Dokumentation von 2011 bis 2014.

Darüber hinaus haben Absätze ihre eigenen Besonderheiten. Wie im Text von The Onion können Sie beim Lesen vieler Absätze das Wesentliche überspringen. Warum sie dann so oft benutzen? Lassen Sie uns ein Experiment aus der Keen IO-Dokumentation durchführen:

Lesen Sie dies schnell:

Ereignissätze können fast jeden Namen haben, es gibt jedoch mehrere Regeln: Der Name sollte nicht mehr als 64 Zeichen enthalten. Es sollte nur ASCII-Zeichen enthalten. Es kann nicht null sein.

Lesen Sie jetzt schnell Folgendes:

Ereignissätze können fast jeden Namen haben, es gibt jedoch einige Regeln:

Der Titel sollte nicht länger als 64 Zeichen sein
Es sollte nur ASCII-Zeichen enthalten
Es kann nicht null sein

In beiden Beispielen genau der gleiche Text. Dies ist nicht Newtons Binom: Das zweite hilft, Informationen besser und schneller aufzunehmen. Wenn der Absatz eine Liste eines beliebigen Typs enthält, verwandeln Sie ihn in eine Liste mit Aufzählungszeichen.

Später werden wir das Layout der Dokumentation und die Navigation genauer besprechen.

Codebeispiele

Was ist API-Dokumentation ohne Code? In vielen unserer Dokumente gibt es Codebeispiele, die die Benutzer tatsächlich lesen. Das Problem ist jedoch, dass sie nicht immer auf den umgebenden Text achten.

Der Kontext im Beispielcode ist entscheidend für den Erfolg des Entwicklers. Entwickler lieben es, schnell zu kopieren und einzufügen. Hier ist ein Beispiel mit der Keen IO-API:

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase);

Der Entwickler kopiert diesen Code schnell und fügt ihn ein. Und ...

Erstens, wie führen sie die Datei überhaupt aus? Wahrscheinlich wie der node file_name.js , aber dies ist nicht im Code enthalten. Man könnte in den Kommentaren oben angeben.

Nun, sie haben es gestartet und ... ReferenceError: Keen is not defined . :-( Der Keen-Client wurde nicht initiiert, oben gibt es keine Import- oder Require-Anweisung und er funktioniert erst nach der Installation der npm-Bibliothek.

Der Benutzer hat es behoben und erneut ausgeführt ... Ratet mal ?! Ein weiterer Fehler! your_project_id und your_write_key fehlen.

All dies könnte deutlicher gemacht werden.

Hier ist ein Beispiel aus der Twilio-Dokumentation, das dem Endbenutzer einen guten Kontext bietet:

Screenshot aus der Dokumentation der Twilio Node Helper- Bibliothek

Dadurch wird sofort klargestellt, wie die Bibliothek installiert, in Ihren Code eingebettet und was im Beispielcode ersetzt werden muss, bevor sie ausgeführt wird.

Kopieren-Einfügen-Fehler

Da die Dokumentation viel Beispielcode enthält, ist das erfolgreiche Kopieren und Einfügen eine ziemlich wichtige Eigenschaft. Hier sind zwei Beispiele, bei denen dies nicht beachtet wird:

 #      $ gem install rails

Scheint ziemlich harmlos, oder? Überlegen Sie noch einmal, was passiert, wenn Sie dies kopieren und in die Befehlszeile einfügen? Sie erhalten höchstwahrscheinlich:

 bash: command not found: $

Ein häufiger Fehler. Entweder möchten Sie, dass der Befehl in der Befehlszeile aussieht, oder Sie kopieren ihn versehentlich. Ich würde empfehlen, $ aufzugeben. Sie können auch das Kopieren und Einfügen dieses Symbols verhindern, damit der Fehler die Benutzer nicht stört.

Ein neueres Beispiel: Haben Sie überprüft, wie einfach es ist, den Code hervorzuheben, den der Benutzer kopieren möchte?

Kelsey Hightower hatte Mühe, den Beispielcode von StackOverflow in der Google Cloud Next-Präsentation zu kopieren.

"Gute Programmierer kopieren, gute Programmierer einfügen"

Hat er es absichtlich gemacht? Wir werden es nie erfahren. Dies ist jedoch ein Beispiel dafür, wie Programmierer versuchen, große Textblöcke auf einigen Dokumentationsseiten hervorzuheben. Stellen Sie sicher, dass die Benutzeroberfläche der Site das Kopieren großer Blöcke erleichtert. Sie können diese Blöcke sogar aufteilen, um die Fragmente einzeln zu erklären. So werden sie für das Kopieren und Verstehen zugänglicher.

"Das ist alles!"

"Das ist alles!" Der Satz scheint aus dem Zusammenhang heraus ziemlich harmlos zu sein, aber stellen Sie sich vor, wie bestimmte Wörter wie „leicht“, „einfach“, „trivial“ und „unkompliziert“ wahrgenommen werden, wenn Sie Probleme haben - nicht großartig! Wenn eine Person feststeckt und versucht, die API zum Laufen zu bringen, wirft ein solcher Satz Zweifel an ihrer Intelligenz auf und lässt sie die Frage stellen: "Also bin ich dumm?" Es demoralisiert.

Vereinfachung

Vereinfachung ist üblich. Es ist am häufigsten unter Anfängern beim Schreiben von Dokumentation. Oft sind die Autoren der Dokumentation gleichzeitig die Entwickler des Systems, so dass ihnen einige Dinge „einfach“ erscheinen. Aber sie entwickelten diese Funktion, schrieben Code dafür, überprüften ihn viele, viele Male und schrieben dann die Dokumentation. Wenn Sie Dutzende Male etwas tun, ist es klar, dass es für Sie „einfach“ sein wird. Aber was ist mit jemandem, der noch nie eine Benutzeroberfläche oder Funktion gesehen hat?

Empathie

Die Wortwahl ist wirklich wichtig. Empathie ist die Fähigkeit, die Gefühle anderer zu verstehen und zu teilen. Wenn wir Empathie zeigen, helfen wir nicht nur Neulingen, sondern auch fortgeschrittenen Benutzern. Dies trägt dazu bei, die potenzielle Anzahl von Benutzern, Anwendungsfällen, Kunden und sogar den Umsatz des Unternehmens zu erhöhen.

Wenn die Dokumentation jedoch von einem erfahrenen Projektentwickler verfasst wird, ist Empathie schwieriger. Hier sind einige hilfreiche Tipps, die mir in der Vergangenheit geholfen haben:

Bitten Sie weniger erfahrene Projektteilnehmer, die Dokumentation ehrlich zu kommentieren.
Ermutigen Sie weniger erfahrene Projektteilnehmer, Beiträge zu Dokumentationspunkten zu leisten oder auf diese zu verweisen, die sie nicht verstehen.
Schaffen Sie eine Umgebung, in der Fragen angeregt werden, einschließlich solcher, die erfahrenen Projektteilnehmern als „offensichtlich“ erscheinen - dies hilft Ihnen, „blinde Flecken“ zu erkennen.
Verwenden Sie Codeprozessoren in Codeüberprüfungs- und CI-Prozessen, um Empathie und Sprachfreundlichkeit für alle Benutzer zu gewährleisten.
Bitten Sie abschließend um einen Kommentar zur Dokumentation realer Benutzer, zeigen Sie ihnen den Text und fragen Sie, ob alles klar ist

Fehlermeldungen als eine Art Dokumentation

In der Regel werden Benutzern eher Fehlermeldungen als Dokumentationen angezeigt. Laut Kate Voss sind „Fehlermeldungen tatsächlich eine Chance“. Ich glaube, dass viele Dokumentationsentwickler diese Gelegenheit verpassen. Es gibt einen Ort für Schulungen, um vertrauensvolle Beziehungen und Benutzererwartungen aufzubauen. Zunächst helfen Sie den Menschen, sich selbst zu helfen.

Kate bei Write The Docs bietet viele nützliche Informationen zum Schreiben von Fehlermeldungen. Ich habe während meiner früheren Arbeit an API-Fehlermeldungen viel gelernt und war auf der anderen Seite der Barrikaden und habe als Entwickler Fehlermeldungen von anderen APIs erhalten.

Kate sagt, dass gute Fehlermeldungen auf drei Prinzipien beruhen:

Bescheidenheit
Menschlichkeit
Nützlichkeit

Bescheidenheit

Sie müssen sich sofort entschuldigen, auch wenn es nicht Ihre Schuld ist. Das übe ich auch im Support.

Ein Beispiel:

Entschuldigung, konnte keine Verbindung zu ___ herstellen. Bitte überprüfen Sie Ihre Netzwerkeinstellungen, stellen Sie eine Verbindung zu einem verfügbaren Netzwerk her und versuchen Sie es erneut.

Menschlichkeit

Verwenden Sie für Menschen lesbare Begriffe und vermeiden Sie Ausdrücke wie "vom Anrufziel ausgelöste Ausnahme". Wenn Sie Code schreiben, für den viele Fehlermeldungen ausgelöst werden, können Sie leicht mit einem klaren Wortschatz davonkommen.

Beispiel (Twilio 401-Statuscodefehler):

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 }

Nützlichkeit

Wenn Sie sich an einen dieser Tipps erinnern, denken Sie an die Nützlichkeit. Teilen Sie dem Benutzer Informationen zur Behebung des Problems mit.

Ein Beispiel:

Das Bild, das Sie hochladen möchten, ist leider zu groß. Versuchen Sie es erneut mit Bildern mit einer Höhe von weniger als 4000 Pixel und einer Breite von 4000 Pixel.

So schreiben Sie Fehlermeldungen

Geben Sie wie bei jeder anderen Dokumentation zuerst wichtige Informationen an. Dies kann erreicht werden, indem zuerst das Objekt und dann die Aktion angegeben werden. Der Benutzer sucht nach einem Ergebnis und nicht nach einem Weg dorthin. Dies ist nützlich, wenn Benutzer schnell nach Fehlermeldungen suchen.

Schlechtes Beispiel:

Drücken Sie die Zurück-Taste, um zur vorherigen Seite zurückzukehren.

Gutes Beispiel:

Verwenden Sie die Zurück-Taste, um zur vorherigen Seite zurückzukehren.

Dokumentationsfehlermeldungen

Ich finde es sehr nützlich, wenn allgemeine API-Fehlermeldungen in der Dokumentation erwähnt werden. Auf diese Weise kann der Dokumentationsautor die Fehlermeldung klären, ohne die Dokumentation zu vergrößern, und gleichzeitig dem Benutzer helfen, zu verstehen, warum der Fehler auftritt.

Twilio veröffentlicht einen vollständigen Katalog mit Fehlern und Warnungen mit möglichen Ursachen und Lösungen. Mit dieser Methode können Sie die tatsächlichen Fehlermeldungen kürzer, aber dennoch nützlich machen.

Im Falle des Fehlers 20003 (Fehler des zuvor erwähnten Statuscodes 401) gibt es viele mögliche Gründe, die im Katalog klar angegeben sind.

Quelle: https://www.twilio.com/docs/api/errors

Stripe macht etwas Ähnliches mit einer detaillierten Beschreibung der verschiedenen Fehlercodes.

Quelle: https://www.twilio.com/docs/api/errors

Sie können Ihre Fehlermeldungen sogar in StackOverflow-Fragen finden. Beantworten Sie sie bescheiden, menschlich und mit Nutzen. Aufgrund der Suchmaschinenoptimierung erhalten Benutzer häufig Ihre Fehlermeldungen auf StackOverflow und nicht auf der eigentlichen Dokumentation.

Tipp: Wenn jemand nicht bescheiden, menschlich und mit Nutzen reagiert hat, können Sie mit genügend "Ruf" die Antworten von StackOverflow bearbeiten.

Wortauswahl

Viele Wörter haben gut etablierte mentale Muster. Beispielsweise sind Wörter wie "Bibliotheken", SDKs, "Wrapper" und "Clients" bereits überladen und werden vom Leser beachtet.

In seinem Vortrag "Selbst für diesen Vortrag ist es schwierig, einen Namen zu finden" auf Write The Docs sagt Ruthie Bendor, warum die Auswahl der richtigen Wörter so schwierig sein kann.

Wir wählen Wörter oft schlecht aus, obwohl wir dies beim Schreiben von Text die ganze Zeit tun. Wie bei vielen SDK-Titeln ruft jedes Wort beim Leser eine Vielzahl von Gefühlen, Ideen und Definitionen hervor. Sie verstehen das vielleicht nicht - und oft machen wir die falschen Annahmen.

In einer solchen Situation gilt das berühmte Sprichwort wie nie zuvor: "Auf dem Gebiet der Informatik gibt es nur zwei schwierige Aufgaben: die Ungültigmachung des Caches und das Erfinden von Namen." Das Zitat wird oft Phil Carleton gutgeschrieben, aber heute gibt es viele Variationen dieses Sprichworts. Manchmal fügen sie am Ende "... und einen Fehler pro Einheit" hinzu. Ruti betrachtet dies als Demonstration, dass Software heutzutage weitgehend auf dem Code oder der Arbeit eines anderen basiert.

Warum bleiben schlechte Objektnamen (oder Dokumentationen) erhalten?

Wie bei der Vereinfachung verstehen wir oft nicht, dass der Name schlecht ist. Das nennt Ruthie das Versagen von Empathie . So kann man sagen, dass das Problem der erfolglosen Wörter mich nicht betrifft, daher existiert es nicht.

Hinweis für die USA: Um versehentlichen Rassismus zu verhindern, verwenden Sie die Wörter "Verbotene Liste" und "Zulässige Liste" anstelle von "Schwarz" und "Weiß".
(Quellen: Andre Staltz und Rails / Rails / Issues / 33677 )

Es erinnert mich immer noch an das, was Ruthie einen Denkfehler für Anfänger nennt. Es ist wie zu sagen: "Es ist mir völlig klar. Ich verstehe nicht, wie jemand das nicht verstehen kann. "

Schließlich erwähnt Ruthie einen Lokalisierungsfehler . Zum Beispiel bedeutet das Wort Bing auf Chinesisch "krank".

Laut einer GitHub Open Source-Umfrage aus dem Jahr 2017 :

Fast 25% der Entwickler, die Englisch lesen und schreiben, sind nicht "sehr gut". Verwenden Sie bei der Kommunikation in einem Projekt eine verständliche und zugängliche Sprache für Personen aus nicht englischsprachigen Ländern.

Berücksichtigen Sie dies, wenn Sie Amerikanismen und Redewendungen in der Dokumentation verwenden? Viele von ihnen sind für Benutzer möglicherweise unverständlich.

Hinweis: Ich bin der festen Überzeugung, dass einer der größten „Tricks“ zur Lösung dieser Probleme die Vielfalt des Dokumentationsteams ist.

Es gibt immer noch Fälle, in denen wir einen Fehler anerkennen, aber wir können oder wollen ihn nicht korrigieren, weil wir ...

An sie gebunden
Wir finden keine Zeit
Wir sehen die Bedeutung nicht
Wir haben keine Agentur, um das Problem zu beheben.

Sie können sagen oder hören: "Aber das ist meine Idee!", "Wer hat meinen Schatz entfernt?" "Wenn wir umbenennen, wird alles kaputt gehen", "Ich glaube nicht, dass die Änderung dieses Namens etwas Wichtiges beeinflusst."

Sie können keine Angst vor Refactoring und Umschreiben haben, wenn es um Dokumentation geht. Wie kann man es verbessern, wenn man der Tatsache nicht zustimmt, dass anfangs nicht die beste Wahl getroffen wurde?

Wie wähle ich die richtigen Wörter aus?

Zu Beginn empfehle ich, eine Frage zu stellen: Welche Wörter verwenden Ihre Benutzer? Unterschiedliche Programmierkreise verwenden unterschiedliche Begriffe. Versuchen Sie nicht, andere zu verwenden. Dies ist nicht nur für Leser nützlich, sondern auch für die Suche und SEO.

Am Ende kommt es unweigerlich auf eine subjektive Bewertung an. Es sind jedoch einige Grundsätze zu beachten. Ruthie sagt, dass schlechte Namen diejenigen sind, die:

peinlich
zu verärgern
irreführen
zu verwirren
beleidigen

Gute Namen dagegen:

zur plötzlichen Klärung beitragen ("das ist es!")
in den Kontext injiziert
erklären
beleuchten
Unterstützung leisten

Ich empfehle, diese Eigenschaften beim Abzug der Dokumentation zu berücksichtigen, um nützliche und ehrliche Bewertungen darüber abzugeben.

Die Auswahl der richtigen Wörter ist schwierig. Es gibt keine Zauberformel. Alle Benutzer sind unterschiedlich, ebenso wie Produktanwendungsfälle. Was für einige funktioniert, funktioniert möglicherweise nicht für andere. Wenn es einfach wäre, hätte jeder eine viel bessere Dokumentation. Ruthie sagt den Entwicklern: „Das Schreiben von Programmen ist eine Übung, um Namen zu erfinden. Beschäftige dich damit. “ Wenn Sie eine Dokumentation für das Programm eines anderen Benutzers schreiben, teilen Sie dem Entwickler mit, ob seine Namen das Ziel nicht erreichen.

Wir schreiben technische Dokumentation: eine Anleitung für den Laien