Dokumentieren von WordPress-Plugins und -Themes

Veröffentlicht: 2017-03-17

Dokumentation ist etwas, das normalerweise nur dann geschätzt wird, wenn es ein Problem gibt und Sie schnell Antworten benötigen. In diesem Artikel gehen wir auf die Gründe ein, warum das Schreiben von Dokumentation für Ihre WordPress-Assets für Ihre Praxis als WordPress-Entwickler und die Qualität der von Ihnen gelieferten Themen und Plugins wichtig ist.

Warum ist Dokumentation wichtig?

Es ist aus vielen Gründen wichtig, eine aktualisierte Dokumentation über Ihre Projekte, Assets oder Produkte zu führen.

Erstens ist es eine übliche Erfahrung, auf etwas zu schauen, das Sie vor 2 Monaten gemacht und seitdem nicht mehr angefasst haben, und keine Ahnung zu haben, was es bedeutet. Wenn Sie es entwickeln, haben Sie alles in Ihrem Kopf, aber dieses Verständnis wird in Zukunft nicht mehr da sein. Entweder die Verwendung von Inline-Code-Kommentaren oder das Schreiben von reinen Textnotizen in Markdown trägt wesentlich dazu bei, Ihr zukünftiges Selbst vor Verwirrung zu bewahren.

Zweitens ist es für andere WordPress-Entwickler hilfreich, Ihre Assets zu dokumentieren. Und das macht auch Sinn, wenn Sie ein einzelner Freiberufler sind (Sie müssen irgendwann mit anderen Leuten zusammenarbeiten). Sie müssen diese Assets entweder verwenden oder werden gebeten, sie zu pflegen und/oder zu aktualisieren. Es ist sehr frustrierend, undokumentierten Code verwenden zu müssen, der von jemand anderem geschrieben wurde, der nicht da ist, um Unterstützung zu bieten oder einige schwierige Teile zu erklären.

Schließlich verleiht die Dokumentation Ihren Produkten diesen „polierten“ Look und Ihre Kunden werden Sie mehr lieben.

5 Prinzipien für eine effektive Dokumentation

Technisches Schreiben ist eine eigene Disziplin und wird verwendet, um technische Informationen klar und unmissverständlich zu kommunizieren. (Nicht nur auf Computer beschränkt, auch Anwälte und Ärzte verwenden beispielsweise ihre eigene Fachsprache). Aus diesem Grund folgt ein Dokument, das als technische Redaktion bezeichnet wird, normalerweise einem bestimmten Stil und einer Reihe von Regeln.

Lassen Sie uns die 5 wichtigsten durchgehen, damit Sie eine effektive Dokumentation für Ihre Produkte schreiben können!

Verwenden Sie lieber weniger Wörter, als Sie normalerweise in Ihrem Schreiben verwenden würden: Jedes Wort sollte einen Zweck haben. Seien Sie direkt und einfach. Dokumentation wird normalerweise gesucht, wenn eine Person in Schwierigkeiten steckt und schnell eine Lösung finden möchte. Beispielsweise ist ein Satz wie „Fehler beim Zerstören von Objekt Q führt zu Speicherlecks“ besser als „Fehler beim Zerstören von Objekt Q führt zu Speicherlecks“.
Verwenden Sie lieber das Aktiv als das Passiv: „ Klicken Sie auf die Schaltfläche oben rechts“ statt „Die Schaltfläche oben rechts muss angeklickt werden “. Die Verwendung einer aktiven Stimme klärt alle Unklarheiten darüber, wer was tut. Passiv wird nur verwendet, wenn Sie sich auf das Objekt und nicht auf das Thema konzentrieren müssen (z. B. ist die Plattform von Pressidium auf Sicherheit ausgelegt ) .
Verwenden Sie eine beschreibende Sprache, wenn Sie Konzepte beschreiben müssen, und einen Imperativ, wenn Sie ein schrittweises Verfahren (wie Tutorials) beschreiben müssen.
Verwenden Sie Aufzählungslisten, wenn Sie Dinge auflisten müssen, die keine Reihenfolge haben, und nummerierte Listen, wenn die Reihenfolge der Punkte wichtig ist.
Stellen Sie sicher, dass Sie die Anweisungen selbst getestet haben, bevor Sie sie präsentieren!

Dokumentieren von WordPress-Plugins

WordPress-Plugins sind wie jede andere Software. Sie bieten eine bestimmte Funktionalität, erfordern eine Installation und manchmal auch eine Fehlerbehebung. Unabhängig davon, wie einfach sie sind, ist es immer eine gute Idee, eine angemessene Menge an Dokumentation bereitzustellen, da nicht alle Benutzer das gleiche technische Know-how haben.

Wenn Sie Ihr WordPress-Plugin auf wordpress.org veröffentlichen, erhalten Sie einen Ort, an dem Sie Installationsanweisungen, Screenshots, häufig gestellte Fragen und sogar ein Änderungsprotokoll ablegen können! Sie mit nützlichen und hochwertigen Informationen zu füllen, ist der Schlüssel, um Ihr Plugin beliebter zu machen:

Schreiben Sie eine überzeugende und nützliche Beschreibung, die den Benutzer letztendlich dazu bringt, Ihr Plugin herunterzuladen und Ihre Website zu besuchen.
Fügen Sie kommentierte Screenshots hinzu, die jedes Konfigurationselement Ihres Plugins erklären, zusätzlich zu denen, die zeigen, wie Ihr Plugin im Browser aussieht.
Stellen Sie in den FAQ Fragen, die nicht abgedroschen sind. Eine gute Möglichkeit, seltsame Grenzfälle zu entdecken, besteht darin, einen nicht computererfahrenen Freund zu bitten, Ihr Plugin zu verwenden.
Haben Sie ein aktualisiertes und gut geschriebenes Änderungsprotokoll. Knappe und kryptische Einzeiler sind ein großes No-Go und zeigen, dass Sie sich nicht wirklich um Ihre Benutzer kümmern.
Stellen Sie sicher, dass der Code Ihres Plugins gut kommentiert ist und den besten Softwarepraktiken und offiziellen Codierungsstandards entspricht.

Wenn Sie nicht weiterkommen und etwas Inspiration brauchen, führen Sie eine kleine Recherche durch und sehen Sie, wie der Text in beliebten Plugins geschrieben ist, die Hunderttausende von Installationen haben, im Vergleich zu den weniger verwendeten.

Dokumentieren von WordPress-Themes

Das Dokumentieren von WordPress-Themes ist eine ganz andere Sache. Das häufigste Problem bei WordPress-Themes besteht darin, nicht zu wissen, welcher Abschnitt welchem visuellen Element entspricht. Nicht jeder beherrscht CSS fließend:

Erstellen Sie eine Hierarchie aller Abschnitte Ihres CSS mit entsprechenden Beschreibungen.
Fügen Sie für jeden Abschnitt einen kommentierten Screenshot hinzu, der jede Funktionalität zusammen mit einem kleinen Beispiel beschreibt. Vergessen Sie nicht, aktive Sprache und imperative Sprache zu verwenden, wenn Sie zeigen, wie etwas zu tun ist, bei dem der Benutzer Anweisungen befolgen muss.
Verwenden Sie ein Tool wie css_doc, um Ihnen zu helfen. Dies erzeugt eine Dokumentation im JavaDoc-Stil und kann veröffentlicht werden.
Manchmal reichen Codekommentare nicht aus und Sie müssen ein Styleguide-Dokument für Ihr CSS-Design erstellen. Styleguide-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. Siehe dieses Beispiel von Google.
Verwenden Sie ein CSS-Framework wie Blueprint CSS. Dies wird Ihnen bei der Entwicklung helfen, indem es Ihnen eine Reihe von Tools zur Verfügung stellt, z. B. ein anpassbares Raster, eine funktionierende Standardtypografie, das Zurücksetzen von Browser-CSS und vieles mehr.
Vergessen Sie auch hier nicht, die offiziellen CSS-Codierungsstandards von WordPress zu konsultieren.