I collaboratori di WordPress cercano la sponsorizzazione per migliorare i documenti per sviluppatori Gutenberg

Gli sviluppatori di WordPress Milana Cap e Jonathan Bossenger stanno avviando una raccolta fondi per migliorare la documentazione degli sviluppatori Gutenberg. La conversazione è iniziata ieri quando Cap ha twittato su come la documentazione venga spesso trascurata quando le aziende assumono collaboratori a tempo pieno per lavorare su WordPress.

"Quando la tua comunità non è in grado di imparare il tuo software, non hai contributori", ha detto Cap. "La documentazione e i tutorial sono molto più importanti per i progetti di software open source di quanto le persone credano".

La prima volta che Cap ha iniziato a chiedere la documentazione di Gutenberg è stato al Community Summit di Parigi, 2017. Da allora ha cercato di indirizzare l'attenzione della comunità su di essa.

"Ci sono molti buchi nella documentazione dell'editor di blocchi per gli sviluppatori, ma il più ovvio è come iniziare", ha detto Cap. “L'inizio della documentazione per gli sviluppatori non dice nulla sull'inizio. “Dice solo cosa puoi fare con un blocco ma non _come_. Gli sviluppatori junior, gli sviluppatori solo PHP e tutti coloro per i quali si intende tale documentazione, non sanno come appare il codice di un blocco, dove inserirlo, come includerlo, ecc, per non parlare di come costruire un blocco personalizzato con componenti personalizzati e impostazioni."

Parte della sfida di documentare l'editor di blocchi è che è in fase di sviluppo attivo. Miglioramenti e perfezionamenti vengono costantemente inviati al plug-in Gutenberg e tenere traccia di ciò che è o non è attualmente disponibile nel core non è sempre facile. Poiché WordPress sta introducendo imminentemente la ricerca nella directory dei blocchi, è un buon momento per formalizzare la documentazione per la creazione dei blocchi.

"Gli esempi di codice mancano in modo allarmante in tutti i documenti", ha affermato Cap. “Gli esempi più basilari esistono, ma manca come costruire effettivamente qualcosa di utilizzabile. Quindi, in questa prima pagina veniamo inviati a un tutorial ma quel tutorial non è ottimizzato per le persone che non hanno mai costruito un blocco prima. Seguendolo, ho e non riuscirò a costruire il blocco".

Marcus Kazmierczak e un team di contributori alla documentazione stanno tentando di ricostruire il tutorial nel manuale ufficiale dell'editor di blocchi. Un problema di GitHub incentrato sull'affrontare le lacune nell'attuale documentazione per sviluppatori ospita una discussione attiva sul modo migliore per riscrivere i documenti per le persone che non conoscono lo sviluppo.

"Questo è un ottimo inizio, ma c'è ancora molto lavoro da fare", ha detto Cap. “La documentazione completa è scritta da persone che conoscono e capiscono React e Gutenberg ma sono 'maledette con la conoscenza'. Non hanno molto tempo da dedicare alla comprensione di quanto gli altri non sanno e in quale dettaglio la documentazione dovrebbe essere scritta. Ad essere onesti, non penso che dovrebbero dedicare il loro tempo a questo. Abbiamo un team di documentazione e siamo disposti a intervenire, ma è necessario un qualche tipo di ponte".

Il problema con la documentazione per sviluppatori Gutenberg: non è amichevole per i nuovi arrivati

"Il 'problema' per come la vedo io con la documentazione dell'editor di blocchi è che, a differenza di altra documentazione di WordPress, è scritta per sviluppatori JavaScript esperti e non è rivolta ai principianti", ha detto Bossenger. “Dovrei anche sottolineare che questa non è affatto una possibilità per le persone che hanno messo insieme la documentazione attuale, e apprezzo tutto il lavoro che hanno fatto finora, ha solo un serio bisogno di una revisione e di un po' di perfezionamento. "

Bossenger ha affermato che in passato WordPress ha reso molto facile per chiunque abbia una conoscenza limitata di PHP creare rapidamente un plug-in o un tema utilizzando action e filter hook. Era facile guardare il codice e capire cosa doveva fare.

"JavaScript moderno, e in particolare React, è una pentola di pesce molto diversa", ha detto Bossenger. “Richiede un livello più profondo di conoscenza di come funziona React, inclusa una nuova terminologia e pratiche. JavaScript moderno può anche creare molta confusione, specialmente se è la prima volta che vedi cose come le funzioni delle frecce o istruzioni if ​​meno dettagliate.

"Se il modo migliore per lavorare con JavaScript in WordPress è stato l'utilizzo di jQuery, il passaggio allo sviluppo Gutenberg basato su React richiede ancora un po' di apprendimento da parte tua."

Dopo aver seguito due corsi prima di poter creare qualsiasi cosa per l'editor, uno su React e uno su Gutenberg, Bossenger ha affermato che l'attuale manuale di Block Editor non è scritto per sviluppatori senza esperienza in React e JavaScript moderno. Crede che sia necessaria una ristrutturazione per spiegare meglio i nuovi concetti e adattarsi a uno schema che è più facile da consumare per un nuovo arrivato. Ha evidenziato il manuale Plugin Developer come esempio in cui i capitoli seguono una struttura e utilizzano una terminologia che è più simile a un libro di testo, introducendo lentamente il lettore a nuovi concetti.

"Direi che sarebbe del tutto possibile per qualcuno senza alcuna conoscenza di plug-in o PHP, armato di questo manuale e Google, creare un semplice plug-in per soddisfare i propri requisiti specifici abbastanza rapidamente", ha affermato Bossenger. "Attualmente il manuale dell'editor di blocchi non è favorevole a questo."

Bossenger non è il solo a ritenere la documentazione attuale. Peter Tasker di Delicious Brains ha recentemente pubblicato un tutorial sulla creazione di un blocco Gutenberg personalizzato. Anche dopo aver lavorato a tempo pieno con React nell'ultimo anno, ha scoperto che i documenti ufficiali dell'editor di blocchi erano "un po' ovunque" e difficili da analizzare.

Dopo che Cap ha commentato la mancanza di aziende che sponsorizzano il lavoro a tempo pieno sulla documentazione, Bossenger ha messo alla prova le acque con un tweet chiedendo se i due potrebbero essere in grado di raccogliere fondi per migliorare i documenti di Gutenberg.

"Proprio come il Block Editor Team (e qualsiasi altro team Make), il team di documentazione è a corto di personale", ha affermato Cap. “Non possiamo permetterci di dedicare pochi membri prima all'apprendimento e poi alla scrittura di documentazione sullo sviluppo con l'editor di blocchi. Questo è il motivo principale del mio tweet. Vedrai contributori sponsorizzati dappertutto ma non nella documentazione e oserò dire che entrambi sono ugualmente importanti".

Prima di lanciare la loro raccolta fondi, Cap e Bossenger hanno in programma di esaminare la documentazione esistente, individuare i buchi ovvi e identificare le domande che rimangono senza risposta per coloro che non conoscono lo sviluppo per l'editor di blocchi.

"Una volta che abbiamo un piano, possiamo prevedere quanto tempo è necessario per ciascuna parte", ha affermato. “Con questo piano andremo alla ricerca di sponsor. Penso che ci sarà un'opzione per donare anche prima, ma nulla è certo a questo punto".

I blocchi sono la nuova frontiera dello sviluppo di WordPress. Investire in una solida documentazione e tutorial per principianti potrebbe avere un impatto importante sull'espansione dell'ecosistema dei blocchi. Ciò avvantaggia anche indirettamente gli utenti poiché finiscono con una directory più diversificata di blocchi tra cui scegliere durante la personalizzazione dei loro siti WordPress.

Bossenger e Cap stanno attualmente lavorando a un piano per i documenti prima di annunciare la loro raccolta fondi. Nel frattempo, chiunque voglia contribuire a migliorare la documentazione sulla creazione dei blocchi può entrare nella discussione su GitHub.