Współtwórcy WordPress szukają sponsorów w celu ulepszenia dokumentacji programistycznej Gutenberga

Twórcy WordPressa, Milana Cap i Jonathan Bossenger, rozpoczynają zbiórkę pieniędzy na ulepszenie dokumentacji programistycznej Gutenberga. Rozmowa rozpoczęła się wczoraj, gdy Cap napisał na Twitterze o tym, jak często pomija się dokumentację, gdy firmy zatrudniają pełnoetatowych współpracowników do pracy nad WordPressem.

„Kiedy twoja społeczność nie jest w stanie nauczyć się twojego oprogramowania, nie masz współpracowników” – powiedział Cap. „Dokumentacja i samouczki są znacznie ważniejsze dla projektów oprogramowania Open Source, niż ludzie sądzą”.

Po raz pierwszy Cap zaczęła prosić o dokumentację Gutenberga na Szczycie Społeczności w Paryżu w 2017 r. Od tego czasu stara się zwrócić na nią uwagę społeczności.

„W dokumentacji edytora bloków jest wiele luk dla programistów, ale najbardziej oczywistą jest to, jak zacząć” — powiedział Cap. „Początek dokumentacji dla programistów nie mówi nic o rozpoczęciu pracy. „Mówi tylko, co możesz zrobić z blokiem, ale nie _jak_. Młodsi programiści, programiści tylko w PHP i każdy, dla kogo przeznaczona jest ta dokumentacja, nie wie, jak wygląda kod bloku, gdzie go umieścić, jak go dołączyć itp., nie mówiąc już o tym, jak zbudować niestandardowy blok z niestandardowymi komponentami i ustawienia.”

Częścią wyzwania związanego z dokumentowaniem edytora bloków jest to, że jest on aktywnie rozwijany. Ulepszenia i udoskonalenia są stale wprowadzane do wtyczki Gutenberg, a śledzenie tego, co jest lub nie jest obecnie dostępne w rdzeniu, nie zawsze jest łatwe. Ponieważ WordPress niedługo wprowadza przeszukiwanie katalogów bloków, jest to dobry moment na sformalizowanie dokumentacji tworzenia bloków.

„Przykłady kodu niepokojąco brakuje we wszystkich dokumentach” – powiedział Cap. „Istnieją najbardziej podstawowe przykłady, ale brakuje tego, jak faktycznie zbudować coś użytecznego. Tak więc na tej pierwszej stronie wysłano nas do samouczka, ale ten samouczek nie jest zoptymalizowany dla osób, które nigdy wcześniej nie budowały bloku. Idąc za nim, zbudowałem i nie uda mi się zbudować bloku.”

Marcus Kazmierczak i zespół twórców dokumentacji próbują odbudować samouczek w oficjalnym podręczniku edytora bloków. Wydanie GitHub skoncentrowane na usuwaniu luk w aktualnej dokumentacji dla programistów jest domem dla aktywnej dyskusji na temat najlepszego sposobu na przepisanie dokumentacji dla osób, które są nowe w blokowaniu rozwoju.

„To bardzo dobry początek, ale wciąż jest wiele do zrobienia” – powiedział Cap. „Pełna dokumentacja jest pisana przez ludzi, którzy znają i rozumieją Reacta i Gutenberga, ale są „przeklęci wiedzą”. Nie mają zbyt wiele czasu na zrozumienie, ile inni nie wiedzą iw jakim stopniu powinna być napisana dokumentacja. Szczerze mówiąc, uważam, że nie powinni poświęcać na to czasu. Mamy zespół ds. dokumentacji i jesteśmy gotowi wskoczyć, ale potrzebny jest jakiś most”.

Problem z dokumentacją programisty Gutenberga: nie jest przyjazny dla nowicjuszy

„Problem”, jak widzę, z dokumentacją edytora bloków polega na tym, że w przeciwieństwie do innych dokumentów WordPressa, jest on napisany dla doświadczonych programistów JavaScript, a nie dla początkujących” – powiedział Bossenger. „Powinienem również zaznaczyć, że to wcale nie jest strzał w stronę ludzi, którzy zebrali aktualną dokumentację i doceniam wszelką pracę, którą wykonali do tej pory, po prostu wymaga poważnego przeglądu i udoskonalenia. ”

Bossenger powiedział w przeszłości, że WordPress bardzo ułatwił każdemu, kto ma ograniczoną wiedzę na temat PHP, szybko zbudować wtyczkę lub motyw za pomocą zaczepów akcji i filtrów. Łatwo było spojrzeć na kod i zrozumieć, co ma robić.

„Współczesny JavaScript, a konkretnie React, to zupełnie inny kociołek rybny” – powiedział Bossenger. „Wymaga to głębszego poziomu wiedzy na temat działania React, w tym nowej terminologii i praktyk. Współczesny JavaScript może być również bardzo mylący, zwłaszcza jeśli po raz pierwszy widzisz funkcje typu strzałka lub mniej szczegółowe instrukcje if.

„Jeżeli najbliżej pracy z JavaScriptem w WordPressie było korzystanie z jQuery, przejście do programowania opartego na React w Gutenbergu nadal wymaga trochę nauki z Twojej strony”.

Po ukończeniu dwóch kursów, zanim zdążył zbudować cokolwiek dla edytora, jednego na React, a drugiego na Gutenbergu, Bossenger powiedział, że obecny podręcznik Block Editor nie jest napisany dla programistów bez doświadczenia w React i nowoczesnym JavaScript. Uważa, że ​​potrzebna jest restrukturyzacja, aby lepiej wyjaśnić nowe koncepcje i dopasować się do wzorca, który jest łatwiejszy do konsumpcji dla nowicjusza. Podkreślił podręcznik Plugin Developer jako przykład, w którym rozdziały mają strukturę i używają terminologii bardziej przypominającej podręcznik, powoli wprowadzając czytelnika w nowe koncepcje.

„Twierdziłbym, że byłoby całkiem możliwe, gdyby ktoś bez wtyczek lub wiedzy na temat PHP, uzbrojony w ten podręcznik i Google, dość szybko zbudował prostą wtyczkę spełniającą ich specyficzne wymagania” – powiedział Bossenger. „Obecnie podręcznik edytora bloków nie sprzyja temu”.

Bossenger nie jest odosobniony w swojej opinii o aktualnej dokumentacji. Peter Tasker z Delicious Brains opublikował niedawno samouczek dotyczący tworzenia niestandardowego bloku Gutenberga. Nawet po pracy z React w pełnym wymiarze godzin przez ostatni rok, stwierdził, że oficjalny edytor bloków dokumentów jest „wszędobylski” i trudny do przeanalizowania.

Po tym, jak Cap skomentował brak firm sponsorujących pełnoetatową pracę nad dokumentacją, Bossenger przetestował wody za pomocą tweeta z pytaniem, czy obaj mogliby zebrać fundusze na ulepszenie dokumentów Gutenberga.

„Tak samo jak w zespole edytora bloków (i każdym innym zespole Make), w zespole dokumentacji brakuje personelu” — powiedział Cap. „Nie możemy pozwolić sobie na poświęcenie kilku członków, aby najpierw nauczyli się, a następnie napisali dokumentację dotyczącą programowania za pomocą edytora bloków. To jest główny powód mojego tweeta. Zobaczysz sponsorowanych współtwórców w całym rdzeniu, ale nie w dokumentacji i ośmielę się powiedzieć, że obaj są równie ważni”.

Przed rozpoczęciem zbiórki pieniędzy Cap i Bossenger planują przejrzeć istniejącą dokumentację, wskazać oczywiste dziury i zidentyfikować pytania, na które nie ma odpowiedzi dla tych, którzy dopiero zaczynają tworzyć edytor bloków.

„Gdy mamy plan, możemy przewidzieć, ile czasu potrzeba na każdą część” – powiedziała. „Dzięki temu planowi będziemy szukać sponsorów. Myślę, że będzie możliwość przekazania darowizny jeszcze wcześniej, ale w tej chwili nic nie jest pewne”.

Bloki to nowa granica rozwoju WordPressa. Inwestowanie w solidną dokumentację i samouczki dla początkujących może mieć duży wpływ na rozszerzenie ekosystemu bloków. To również pośrednio przynosi korzyści użytkownikom, ponieważ otrzymują bardziej zróżnicowany katalog bloków do wyboru podczas dostosowywania swoich witryn WordPress.

Bossenger i Cap pracują obecnie nad planem dla dokumentów przed ogłoszeniem zbiórki funduszy. W międzyczasie każdy, kto chce przyczynić się do ulepszenia dokumentacji tworzenia bloków, może włączyć się do dyskusji na GitHubie.