WordPress-Mitwirkende suchen Sponsoring für die Verbesserung der Gutenberg-Entwicklerdokumentation

Die WordPress-Entwickler Milana Cap und Jonathan Bossenger starten eine Spendenaktion zur Verbesserung der Gutenberg-Entwicklerdokumentation. Das Gespräch begann gestern, als Cap darüber twitterte, dass die Dokumentation oft übersehen wird, wenn Unternehmen Vollzeitmitarbeiter für die Arbeit an WordPress einstellen.

„Wenn Ihre Community Ihre Software nicht lernen kann, haben Sie keine Mitwirkenden“, sagte Cap. „Dokumentation und Tutorials sind für Open-Source-Software-Projekte viel wichtiger, als man denkt.“

Das erste Mal, dass Cap begann, nach einer Gutenberg-Dokumentation zu fragen, war auf dem Community Summit in Paris im Jahr 2017. Seitdem versucht sie, die Aufmerksamkeit der Community darauf zu lenken.

„Es gibt viele Lücken in der Blockeditor-Dokumentation für Entwickler, aber die offensichtlichste ist, wie man anfängt“, sagte Cap. „Der Beginn der Dokumentation für Entwickler sagt nichts über den Einstieg aus. „Es sagt nur, was man mit einem Block machen kann, aber nicht _wie_. Junior-Entwickler, Nur-PHP-Entwickler und jeder, für den diese Dokumentation gedacht ist, weiß nicht, wie der Code eines Blocks aussieht, wo er platziert wird, wie er eingebunden wird usw., geschweige denn, wie man einen benutzerdefinierten Block mit benutzerdefinierten Komponenten erstellt und die Einstellungen."

Ein Teil der Herausforderung bei der Dokumentation des Blockeditors besteht darin, dass er aktiv weiterentwickelt wird. Verbesserungen und Verfeinerungen werden ständig an das Gutenberg-Plugin weitergegeben, und es ist nicht immer einfach, den Überblick darüber zu behalten, was derzeit im Kern verfügbar ist oder nicht. Da WordPress in Kürze die Blockverzeichnissuche einführt, ist es ein guter Zeitpunkt, die Dokumentation zur Blockerstellung zu formalisieren.

„Codebeispiele fehlen erschreckenderweise in allen Dokumenten“, sagte Cap. „Es gibt die grundlegendsten Beispiele, aber es fehlt, wie man tatsächlich etwas Brauchbares baut. Auf dieser ersten Seite werden wir also zu einem Tutorial geschickt, aber dieses Tutorial ist nicht für Leute optimiert, die noch nie zuvor einen Block gebaut haben. Danach muss und werde ich den Block nicht bauen.“

Marcus Kazmierczak und ein Team von Dokumentationsmitarbeitern versuchen, das Tutorial im offiziellen Blockeditor-Handbuch nachzubauen. Eine GitHub-Ausgabe, die sich darauf konzentriert, Lücken in der aktuellen Entwicklerdokumentation zu schließen, ist die Heimat einer aktiven Diskussion darüber, wie die Dokumentation für Leute, die neu in der Blockentwicklung sind, am besten umgeschrieben werden kann.

„Das ist ein sehr guter Anfang, aber es gibt noch viel zu tun“, sagte Cap. „Die vollständige Dokumentation wird von Leuten geschrieben, die React und Gutenberg kennen und verstehen, aber ‚mit Wissen verflucht' sind. Sie haben nicht viel Zeit, um zu verstehen, wie viel andere nicht wissen und in welchem ​​Detail Dokumentation geschrieben werden sollte. Um ehrlich zu sein, denke ich nicht, dass sie ihre Zeit damit verbringen sollten. Wir haben ein Dokumentationsteam und sind bereit, einzuspringen, aber eine Art Brücke ist notwendig.“

Das Problem mit der Gutenberg-Entwicklerdokumentation: Sie ist nicht für Neueinsteiger geeignet

„Das ‚Problem', wie ich es bei der Blockeditor-Dokumentation sehe, ist, dass sie im Gegensatz zu anderer WordPress-Dokumentation für erfahrene JavaScript-Entwickler geschrieben wurde und sich nicht an Anfänger richtet“, sagte Bossenger. „Ich sollte auch betonen, dass dies keineswegs ein Schuss auf die Leute ist, die die aktuelle Dokumentation zusammengestellt haben, und ich schätze jede einzelne Arbeit, die sie bisher geleistet haben, es bedarf nur ernsthaft einer Überprüfung und einiger Verfeinerung. ”

Bossenger sagte, dass WordPress es in der Vergangenheit für jeden mit begrenzten PHP-Kenntnissen sehr einfach gemacht habe, schnell ein Plugin oder Design mit Aktions- und Filter-Hooks zu erstellen. Es war einfach, sich den Code anzusehen und zu verstehen, was er tun sollte.

„Modernes JavaScript, und insbesondere React, ist ein ganz anderer Fischkessel“, sagte Bossenger. „Es erfordert ein tieferes Wissen darüber, wie React funktioniert, einschließlich neuer Terminologie und Praktiken. Modernes JavaScript kann auch sehr verwirrend sein, besonders wenn Sie zum ersten Mal Dinge wie Pfeilfunktionen oder weniger ausführliche if-Anweisungen sehen.

„Wenn Sie der Arbeit mit JavaScript in WordPress am nächsten gekommen sind, wenn Sie jQuery verwendet haben, erfordert der Wechsel zur React-basierten Gutenberg-Entwicklung immer noch etwas Lernen von Ihrer Seite.“

Nachdem er zwei Kurse besucht hatte, bevor er etwas für den Editor bauen konnte, einen über React und einen über Gutenberg, sagte Bossenger, dass das aktuelle Block-Editor-Handbuch nicht für Entwickler ohne Erfahrung in React und modernem JavaScript geschrieben sei. Er glaubt, dass es einer Umstrukturierung bedarf, um neue Konzepte besser zu erklären und einem Muster zu entsprechen, das für einen Neuling einfacher zu konsumieren ist. Er hob das Plugin-Entwicklerhandbuch als Beispiel hervor, in dem die Kapitel einer Struktur folgen und eine Terminologie verwenden, die eher einem Lehrbuch ähnelt und den Leser langsam an neue Konzepte heranführt.

„Ich würde argumentieren, dass es für jemanden ohne Plugin- oder PHP-Kenntnisse, bewaffnet mit diesem Handbuch und Google, durchaus möglich wäre, ein einfaches Plugin zu erstellen, das seine spezifischen Anforderungen recht schnell erfüllt“, sagte Bossenger. „Aktuell ist das Blockeditor-Handbuch dafür nicht förderlich.“

Bossenger ist mit seiner Meinung zur aktuellen Dokumentation nicht allein. Peter Tasker von Delicious Brains hat kürzlich ein Tutorial zum Erstellen eines benutzerdefinierten Gutenberg-Blocks veröffentlicht. Selbst nachdem er im vergangenen Jahr Vollzeit mit React gearbeitet hatte, fand er die offiziellen Blockeditor-Dokumente „irgendwie überall“ und schwer zu analysieren.

Nachdem Cap den Mangel an Unternehmen kommentierte, die Vollzeitarbeit an der Dokumentation sponsern, testete Bossenger das Wasser mit einem Tweet, in dem er fragte, ob die beiden in der Lage sein könnten, Spenden für die Verbesserung der Gutenberg-Dokumentation zu sammeln.

„Genauso wie das Block-Editor-Team (und jedes andere Make-Team) ist das Dokumentations-Team unterbesetzt“, sagte Cap. „Wir können es uns nicht leisten, nur wenige Mitglieder dafür einzusetzen, zuerst zu lernen und dann Dokumentationen zur Entwicklung mit dem Blockeditor zu schreiben. Das ist der Hauptgrund für meinen Tweet. Sie werden gesponserte Mitwirkende überall im Kern sehen, aber nicht in der Dokumentation, und ich wage zu behaupten, dass beide gleich wichtig sind.“

Vor dem Start ihrer Spendenaktion planen Cap und Bossenger, die vorhandene Dokumentation durchzugehen, offensichtliche Lücken zu lokalisieren und Fragen zu identifizieren, die für diejenigen, die neu in der Entwicklung für den Blockeditor sind, unbeantwortet bleiben.

„Sobald wir einen Plan haben, können wir vorhersagen, wie viel Zeit für jeden Teil benötigt wird“, sagte sie. „Mit diesem Plan werden wir uns auf die Suche nach Sponsoren machen. Ich denke, es wird auch vorher eine Möglichkeit geben, zu spenden, aber zu diesem Zeitpunkt ist noch nichts sicher.“

Blöcke sind die neue Grenze der WordPress-Entwicklung. Die Investition in eine solide Dokumentation und Tutorials für Anfänger könnte einen großen Einfluss auf die Erweiterung des Block-Ökosystems haben. Dies kommt auch den Benutzern indirekt zugute, da sie am Ende ein vielfältigeres Verzeichnis von Blöcken zur Auswahl haben, wenn sie ihre WordPress-Sites anpassen.

Bossenger und Cap arbeiten derzeit an einem Plan für die Dokumente, bevor sie ihre Spendenaktion ankündigen. In der Zwischenzeit kann sich jeder, der zur Verbesserung der Dokumentation zur Blockerstellung beitragen möchte, an der GitHub-Diskussion beteiligen.