Eine Einführung in das Schreiben einer guten Dokumentation
Veröffentlicht: 2015-06-06
Dieser Beitrag wurde von Gastautor Jeff Matson beigesteuert. Jeff ist der Leiter der Dokumentation für GravityForms. Er ist der Schöpfer des WordPress-Plugins Heartbeat Control und ein Fan der 90er Jahre.
Die Dokumentation ist oft der am meisten unterschätzte Teil des Entwicklungsprozesses. Wenn wir uns Rockstars in der WordPress-Community ansehen, schauen wir normalerweise auf Entwickler, Designer und Vermarkter. Es ist wenig über die Dokumentationsautoren da draußen bekannt, die ihr Blut, ihren Schweiß und ihre Tränen vergießen, um sicherzustellen, dass alles reibungslos läuft.
In diesem Beitrag geht es um diejenigen, die Tag für Tag auf endlose Codezeilen starren, um zu entschlüsseln, was der Entwickler dachte, und die wahre Bedeutung hinter dem vorhandenen Code.
Gute Dokumentation ist mehr als Worte
Gute Dokumentationsautoren bieten mehr als eine Bedienungsanleitung, sie bieten ein Erlebnis. Ich kenne ausgezeichnete Dokumentaristen, gecoachte Anfänger, und der größte Unterschied zwischen ihnen besteht darin, das Gehirn derer zu verstehen, die es lesen. Genau wie ein Roman hat die Dokumentation einen Fluss, der den Leser interessiert hält und mehr Informationen aufnimmt, als ihm bewusst ist.
Qualitätsdokumentation richtet sich an die Benutzer, die sie am ehesten lesen werden. Es bietet auch einen Anhaltspunkt für diejenigen, die es eher nicht lesen werden. Wenn Sie beispielsweise einen bestimmten Hook dokumentieren, wird normalerweise davon ausgegangen, dass ein Entwickler ihn lesen wird, aber was ist mit denen, die wenig Entwicklungserfahrung haben?
Ein guter Dokumentationsautor bietet einen Bezugspunkt für diejenigen, die mehr Schubs in die richtige Richtung benötigen, ohne den Support kontaktieren zu müssen, um es ihnen zu erklären.
Dokumentation hat einen größeren Einfluss als Sie denken
Die meisten ignorieren die Dokumentation einfach und schieben sie in den endlosen Abgrund, bis sie es nicht mehr ertragen können. Ich bin in einigen Fällen der gleichen Sache schuldig. Was diese Leute nicht erkennen, ist, dass jedes Mal, wenn ihr Plugin oder Thema undokumentiert bleibt, die Benutzererfahrung leidet.
Werfen wir einen Blick auf Ihr häufigstes Support-Ticket. Wenn Sie dieses Problem besser dokumentieren würden, würden diese Tickets dann vollständig verschwinden? Wahrscheinlich nicht. Würden Sie weniger Tickets zu diesem Problem erhalten und Ihre Produktivität oder die Ihres Support-Mitarbeiters steigern? Ich garantiere es. Ich denke, wir alle könnten weniger Support-Tickets gebrauchen.
Wie ich bereits erwähnt habe, hat die Dokumentation einen dramatischen Einfluss auf die Benutzererfahrung. Wenn der Benutzer in der Lage ist, die Informationen einfach und effizient zu finden, hat er sowohl seine eigene als auch Ihre Zeit gespart. Die durchschnittliche weltweite Lebenserwartung beträgt 66,57 Jahre und Ihre Benutzer würden lieber etwas anderes mit ihrem Leben anfangen, als mit schlecht geschriebener Dokumentation herumzuspielen.
Wenn ein Kunde sieht, dass Sie viel Zeit und Mühe in Ihre Dokumentation gesteckt haben, wird er Sie bewusst oder unbewusst besser zu schätzen wissen. Eine gute Dokumentation zeigt, dass Sie sich nach dem ersten Verkauf um sie kümmern.
Wurden Sie schon einmal auf dem Trockenen gelassen, nachdem Sie Ihr hart verdientes Geld ausgegeben haben, und haben den Kauf bald bereut? Ich denke, das haben wir alle. Mit der richtigen Dokumentation können Sie vermeiden, dieses Gefühl an Ihre Kunden weiterzugeben.
Wie können Sie eine bessere Dokumentation schreiben?
Der erste Schritt ist, damit aufzuhören, es zu vermeiden. Sobald Sie gut darin sind, ist das Schreiben von Dokumentationen eine angenehmere Erfahrung, als Sie denken. Tatsächlich wird es zur zweiten Natur. Wie alles auf der Welt macht Übung den Meister.
Einer der ersten Schritte, den Sie unternehmen sollten, wenn Sie sich entscheiden, Ihre Dokumentation auf die nächste Stufe zu heben, ist die Bestimmung Ihrer Schmerzpunkte. Worüber werden Sie kontaktiert? Wenn du anfängst, blindlings über Dinge zu schreiben, wirst du vielleicht feststellen, dass das, worüber du schreibst, nicht die Wirkung hat, die du dir wünschst.
Eine der besten Techniken, die ich entdeckt habe, besteht darin, die Anzahl der dokumentierten Tickets im Vergleich zu den nicht dokumentierten Tickets zu verfolgen und die nicht dokumentierten in Kategorien aufzuteilen. Auf diese Weise können Sie Ihre Schmerzpunkte besser anvisieren und die Teile überarbeiten, die möglicherweise nicht so hilfreich sind, wie sie sein sollten.
Nachdem Sie bestimmt haben, welche Dokumentation Sie schreiben sollten, sollten Sie Ihre Zielgruppe bestimmen und sie in Entwickler, Benutzer und Hauptbenutzer aufteilen. Dies hilft Ihnen, auf diese bestimmte Zielgruppe einzugehen. Wir gehen etwas später darauf ein, wie Sie diese Benutzer ansprechen können.
Als Nächstes möchten Sie das Dokument aufschlüsseln. Für Entwickler sollten Sie es in Rohinformationen (akzeptierte Argumente, Rückgabewerte usw.), spezifische Beispiele und Anwendungsfälle aufschlüsseln. Für Benutzer ist die beste Vorgehensweise eine exemplarische Vorgehensweise. Jeder Schritt, den sie unternehmen müssen, egal wie trivial er erscheinen mag, ist entscheidend.
Sagen Sie es ihnen bei jedem Schritt. Die Dokumentation für Power-User ist einem Benutzerszenario sehr ähnlich, aber strukturierter und durchsuchbarer. Seien Sie klar, aber erlauben Sie ihnen, leicht dorthin zu springen, wo sie hin müssen, ohne zuerst den vorherigen Schritt zu lesen.
Die Kunst, bessere Dokumentationen zu schreiben
Wenn es um die Kunst des Schreibens Ihrer Dokumentation geht, schreiben Sie auf eine Weise, die Ihr Publikum am besten anspricht, aber verwenden Sie auch eine einfache Sprache, von der Sie wissen, dass sie sie verstehen wird. Einer der besten Gründe dafür sind Übersetzungen. Während Google Translate hervorragende Arbeit leistet, ist es viel einfacher, das einfache Vokabular eines Fünftklässlers zu übersetzen als das, was in einer Abschlussarbeit enthalten ist.
Scheuen Sie sich nicht, innerhalb Ihrer Inhalte auf relevante Inhalte zu verlinken. Auf diese Weise können Sie vermeiden, sich durch mehrere Dokumente zu wiederholen, und dem Leser ermöglichen, zurückzugehen, wenn er weitere Informationen zu einem bestimmten Thema benötigt. Schließlich besteht Ihr Hauptziel darin, den Benutzer glücklich zu machen und Zeit zu sparen.
Der Dokumentationsprozess wird nicht beendet, nachdem Sie auf die Schaltfläche „ Veröffentlichen “ geklickt haben. Gehen Sie zurück und überarbeiten Sie jedes Dokument nach Bedarf. Gehen Sie fast unmittelbar nach der Veröffentlichung des Dokuments zurück und prüfen Sie, ob die von Ihnen verfolgten Support-Tickets abgelehnt wurden und der Traffic zu diesem bestimmten Artikel zugenommen hat. Normalerweise hilft es, wenn Sie mehr Zugriffe auf einen Artikel erhalten. Wenn Sie mehr Verkehr, aber die gleiche Anzahl von Support-Tickets erhalten, sollten Sie sich diesen Artikel ansehen, um zu sehen, warum.
Was wir gelernt haben
Erstens hoffe ich, dass Sie, nachdem Sie es bis hierher geschafft haben, ein besseres Verständnis für diejenigen haben, die in den Schützengräben die Dokumentation schreiben, die die meisten von uns für selbstverständlich halten. Es ist wirklich eine Kunstform, die viele von uns, die beruflich Dokumentationen schreiben, wirklich genießen und viele, viele Stunden damit verbringen.
Ich hoffe auch, dass Sie nach diesem Artikel mehr über Ihre vorhandene Dokumentation nachdenken und wie sie verbessert werden kann. Korrekte Dokumentation kann äußerst lohnend sein und in der Praxis sogar Spaß machen.
Dokumentieren Sie früh, dokumentieren Sie oft. Ein großartiges Produkt ist mehr als nur großartiger Code, es ist auch wunderbar dokumentiert.