Produktdokumentation für WordPress-Profis

Veröffentlicht: 2017-07-28

Produktdokumentation wird in der Regel als belanglos angesehen, da kann man sparen. Es wird nicht als etwas angesehen, das dem Kunden einen Mehrwert bieten kann oder möglicherweise wichtige Geschäftsbereiche wie Einnahmen und Marketing beeinträchtigen könnte. Zugegeben, als WordPress-Profi müssen Sie keine Dokumentation auf die gleiche Weise schreiben wie Atlassian oder Cisco. Wenn Menschen an „Dokumentation“ denken, kommen ihnen normalerweise Bilder von dicken, gedruckten Benutzerhandbüchern in den Sinn, die alphabetisch indiziert in einem sehr großen Regal stehen, das nie jemand liest.

Aber das hat sich geändert:

Mit dem Aufkommen von Agile und DevOps ist Versandsoftware schneller geworden und auch der Entwicklungszyklus hat an Dynamik gewonnen. Infolgedessen spiegelt die Dokumentation jetzt den aktuellen Stand in der neuesten Version wider, anstatt etwas Statisches zu sein, das für immer auf Papier geschrieben wurde. Dokumentation ist in den Entwicklungszyklus integriert und wird ebenso häufig aktualisiert wie Software.

Warum sollten sich WordPress-Profis um die Produktdokumentation kümmern?

Nützliche, aktuelle Dokumentation erleichtert nicht nur das Leben Ihrer Benutzer, sondern fügt auch einen Grad an Politur hinzu, der zu einem unvergleichlichen Marketing-Asset wird. Umgekehrt wirkt sich eine schlechte Dokumentation negativ aus. Sie haben das wahrscheinlich selbst erlebt: Sie hatten ein Problem, für das Sie sich bemüht haben, die Lösung in der Dokumentation zu finden, und als Sie es nicht geschafft haben, waren Sie frustriert (und wahrscheinlich wütend). Es wird nur noch schlimmer, wenn Sie für das Produkt bezahlen.

Wenn Sie in einer WordPress-Agentur arbeiten, wird die Bereitstellung von Dokumentation in allen Bereichen eines Projekts, vom ersten Design bis zu den Assets, ein Maß an Professionalität hinzufügen, das zeigt, dass:

  1. Sie achten auf Details.
  2. Sie kümmern sich genug um Ihren Kunden, um die Extrameile zu gehen.
  3. Sie sind transparent und sicher in Ihren Design- und technischen Projektentscheidungen.

Mike Puterbaugh, VP of Marketing bei MindTouch, schrieb einen Mashable-Artikel, der die 5 Gründe beschreibt, warum Ihre Produktdokumentation ein Marketing-Asset ist. Er schloss mit folgendem:

Es ist kein sexy Unterfangen, aber es wird Ihnen den Respekt Ihrer Kollegen, eine effektivere Unternehmensführung und ein kollaborativeres Team einbringen. Denn es geht nicht um dieses Quartal oder dieses Jahr, sondern darum, Wettbewerbsvorteile und langfristiges Wachstum zu beeinflussen.

Jetzt, da wir genug Motivation aufgebaut haben, werden wir:

  1. Entdecken Sie die verschiedenen Arten von Produktdokumentationen, die für WordPress relevant sind.
  2. Besprechen Sie die Anforderungen der einzelnen Dokumentationstypen und bieten Sie umsetzbare Ratschläge an.
  3. Bieten Sie eine erste Anleitung, wie Sie die Produktdokumentation planen und zusammenarbeiten können. Vor allem, wenn Sie in einer WordPress-Agentur arbeiten.

Arten der WordPress-Produktdokumentation

Bei einem WordPress-Produkt geht es nicht nur um Plugins und Themes. In diesem Abschnitt werden wir auch die Online-Hilfe, REST-APIs und eine merkwürdige Sache namens Mikroinhalt besprechen.

WordPress-Plugins

Die WordPress-Plugin-Dokumentation muss zwei Gruppen bedienen: Benutzer und Entwickler. Die Dokumentationsanforderungen sind jeweils unterschiedlich, ebenso wie der verwendete Schreibstil.

Hosten Sie Ihre Website mit Pressidium

60- TÄGIGE GELD-ZURÜCK-GARANTIE

SEHEN SIE UNSERE PLÄNE

Benutzer

Der Dokumentationsbedarf der Benutzer dreht sich hauptsächlich um Fehlerbehebung und Konfiguration. Hinzu kommt, dass Sie Ihr Plugin ansprechend präsentieren müssen, um die Nutzer zum Ausprobieren zu bewegen. Jedes Plugin hat eine eigene Seite im WordPress-Plugin-Markt. Beachten Sie dabei folgende Punkte:

  • Schreiben Sie eine überzeugende und nützliche Beschreibung, die zum Herunterladen und Verwenden anregt.
  • Fügen Sie kommentierte Screenshots von Ihrer Dashboard-Plugin-Konfigurationsseite mit Beschreibungen hinzu.
  • Stellen Sie Fragen in die FAQ, die nützlich und nicht abgedroschen sind.
  • Haben Sie ein aktualisiertes und gut geschriebenes Änderungsprotokoll. Fügen Sie dort keine kryptischen oder prägnanten Notizen hinzu.

Sie sollten bedenken, dass Benutzer, die die Dokumentation verwenden, wahrscheinlich in Eile sind und darauf bedacht sind, eine Lösung zu finden. Schreiben Sie klar, einfach und prägnant. Machen Sie es ihnen nicht schwerer, als es ohnehin schon ist.

Entwickler

Neben der Befolgung bewährter Softwarepraktiken und offizieller PHP-Codierungsstandards sollten Sie Ihre Aufmerksamkeit auf die folgenden Bereiche richten:

Plugin-Hooks

Diese erledigen die Arbeit, das Verhalten von WordPress zu ändern. Sehr wahrscheinlich verwendet Ihr WordPress-Plugin diese. Da Plugin-Hooks ein wichtiger Teil des Codes sind, solltest du dokumentieren, wie du sie verwendest und an welchen WordPress-Funktionen sie beteiligt sind.

Vorlagen-Tags

Vorlagen-Tags sind eine weitere Möglichkeit für ein WordPress-Plugin, die Funktionalität zu verbessern. Dokumentieren Sie die von Ihnen geschriebenen Template-Tag-Funktionen. Fügen Sie Beispiele hinzu, wie andere Benutzer oder Entwickler die Tags auf ihrer WordPress-Site verwenden können.

Optionen

Optionen sind eine Möglichkeit, bestimmte Informationen in einer WordPress-Datenbank zu speichern. Dies geschieht über die Funktionen add_option und get_options. Dokumentieren Sie in diesem Fall die Parameter, die Sie an diese Funktionen übergeben.

Datenbank

Plugins lesen und schreiben häufig viele verschiedene Dinge aus einer Datenbank. Da dies grundlegende Operationen sind, wird ihre Dokumentation anderen Entwicklern sehr dabei helfen, zu verstehen, wie Ihr Plugin funktioniert.

WordPress-Themen

Es gibt zwei verschiedene Bereiche, in denen Sie Dokumentationen für Themen erstellen können. Die erste sind die Quelldateien. Kommentierte CSS-Dateien sind leichter zu verstehen und zu lesen als solche ohne. Verwenden Sie ein Tool wie css_doc, um Ihnen zu helfen. Dadurch wird eine Dokumentation im JavaDoc-Stil erstellt, die veröffentlicht werden kann:

Der andere Bereich sind Styleguides. Diese Dokumente beschreiben, wie Elemente aussehen müssen und in welchen Fällen sie verwendet werden müssen. Sie erzwingen Konsistenz und erleichtern auch die Zusammenarbeit. Sie können den Hubspot-Artikel 20 atemberaubende Beispiele für Marken-Styleguides lesen, da er viele großartige Beispiele enthält.

Vergessen Sie auch hier nicht, die offiziellen CSS-Codierungsstandards von WordPress zu konsultieren.

Die detaillierte Dokumentation von Designelementen hilft auch beim Onboarding neuer Mitarbeiter, wenn Sie eine WordPress-Agentur sind. Styleguides können als Tutorials oder Referenzmaterial für die Arbeit mit neuen und früheren Kunden verwendet werden.

Onlinehilfe

Da die Online-Hilfe darauf abzielt, ein bestimmtes Benutzerproblem zu lösen, ist es am besten, mit einer Liste häufiger Aufgaben und Probleme zu beginnen. Obwohl die Liste zunächst nicht vollständig sein wird, nehmen Sie sich die Zeit, so viele konkrete Gegenstände wie möglich herzustellen. Die Idee ist, eine Online-Hilfedatei für jede dieser Aufgaben und Probleme zu schreiben und sie mit verwandten Informationen zu verknüpfen. Sie können Benutzerreisen erstellen, um die verschiedenen Pfade darzustellen, die ein Benutzer innerhalb Ihrer Anwendung einschlagen und ausführen kann. Das Eintauchen in Support-E-Mails, um häufige Fragen und problematische Bereiche zu erkennen, ist eine gute Möglichkeit, Ihre Wissensdatenbank auf dem neuesten Stand und nützlich zu halten.

Barry J. Rosenberg, Autor von Spring into Technical Writing, gibt die folgenden Ratschläge, um gute Hilfedateien zu schreiben:

Halten Sie jede Hilfedatei so kurz wie möglich. Bevorzugen Sie nummerierte Listen gegenüber Listen mit Aufzählungszeichen. Schweifen Sie nicht ab, machen Sie keine Fußnoten und wollen Sie nicht. Konzentrieren Sie sich in jeder Hilfedatei auf eine einzelne einzelne Aufgabe.

Mikroinhalt

Microcontent hat zwei Definitionen: Die erste ist Inhalt wie Überschriften und Abschnitte, die Benutzer überfliegen, um das Wesentliche eines bestimmten Artikels zu erhalten. Das zweite sind kleine Inhalte, die für sich alleine stehen können und zur Verbesserung der Benutzererfahrung verwendet werden. Ein besonders gutes Beispiel, das wir im Sinn haben, ist Slacks „mehrere Leute tippen …“-Bit. (obwohl Slack voller hervorragend geschriebener Mikroinhalte ist).

Dieses Bit wird ausgelöst, wenn mehr als 3 Personen gleichzeitig in denselben Kanal tippen. Anstatt nur eine Liste von Personen auszudrucken, die gerade tippen, nimmt Slack diese langweilige Information und fügt ihr etwas Spaß hinzu. Die Diskussion beginnt wirklich heiß zu werden, und das merkt man. Es ist ein hervorragendes Beispiel dafür, wie Produktdokumentationen (Anwendungsmeldungen gehören dazu, oder?) die Leute dazu bringen, über Sie zu sprechen (und urkomische Memes wie die oben genannten erstellen).

REST-API

Die Dokumentation von REST-APIs ist eine eigene Kunst für sich. Wie bei allen technischen Texten sollten Sie bei Definitionen auf Prägnanz, Klarheit und Einfachheit abzielen. Da REST-APIs ihr eigenes Format und ihre eigenen Feinheiten haben, könnten Sie nichts Schlimmeres tun, als den exzellenten Leitfaden für die Dokumentation von APIs von Tom Johnson in seinem Blog „I’d Rather Be Writing“ zu studieren.

Mitarbeit und Planungsdokumentation

Letztendlich sollte die Dokumentation Teil des Produktdesigns sein. Daher sollten Sie es so angehen, als hätten Sie eine zusätzliche Pipeline in Ihrem Softwarezyklus. Das bedeutet, dass Sie Software-Repositories verwenden, um die aktuellste Dokumentationsversion zu speichern, Bug-/Issue-Tracker verwenden, um Aufgaben und Probleme zu überwachen, die Planung von Dokumentationsprojekten in Ihre Roadmap aufnehmen und nicht zuletzt mit anderen Personen zusammenarbeiten. Ein grober Überblick über den Anfang könnte wie folgt aussehen:

  1. Notieren Sie alles , was der Benutzer wissen möchte, sowie Bereiche, für die Sie Text schreiben müssen.
  2. Wenn Sie alles haben, gruppieren Sie sie in Kategorien und bilden Sie Dokumenttitel.
  3. Schreiben Sie für jedes Dokument eine Spezifikation mit Details wie Titel, Beschreibung, Zielgruppe, Medien (welche Form wird das Dokument haben), Länge, wie viel Zeit es dauern wird usw.
  4. Fügen Sie die Schätzungen aus den Dokumentationsspezifikationen Ihrer Projektplanung hinzu.

Da die Produktdokumentation alle Bereiche umfasst, ist es fast sicher, dass Sie mit verschiedenen Personen innerhalb der Organisation zusammenarbeiten müssen. Es ist eine gute Idee, sich zusammenzusetzen und sich auf eine Art Prozess zu einigen, wie das alles ablaufen soll. Wie bei jedem Projekt sollten Sie die Beteiligten identifizieren, die technische Unterstützung leisten, sowie diejenigen, die Änderungen überprüfen und bearbeiten.

Hosten Sie Ihre Website mit Pressidium

60- TÄGIGE GELD-ZURÜCK-GARANTIE

SEHEN SIE UNSERE PLÄNE

Es sollte verschiedene Phasen des Prozesses geben. Diese sollten darlegen, wo Informationen gesammelt werden, wann das Dokument geschrieben wird, wann es für das literarische Korrekturlesen, für technische Kommentare, die Veröffentlichung und dergleichen bereit ist. Betonen Sie den Unterschied zwischen literarischen, technischen und inhaltlichen Kommentaren. Es ist zum Beispiel nicht wirklich sinnvoll, wenn Sie einen Teamleiter bitten, Ihr Dokument zu kommentieren, und Sie anstelle von fachlich relevanten Informationen Schreie nach Grammatik und Zeichensetzung erhalten.

Schließen

Produktdokumentation ist ein Gut, das sich langfristig auszahlt. Es gibt Ihrem Kunden einen Mehrwert. Es könnte sogar so gut sein, wie zum Beispiel die API-Dokumentation von Stripe, dass die Leute in Foren davon schwärmen. Dies baut Engagement auf und bewirbt Ihre Marke und Ihr Produkt auf natürliche und kraftvolle Weise. Gepaart mit kreativem Microcontent erreicht es, was Mike Puterbaugh meint, wenn er sagt, dass Produktdokumentation die „Geheimwaffe des Marketings“ ist.