Tutorial precedente: Developing Discourse Plugins - Part 6 - Add acceptance tests
Hai creato il tuo plugin, lo hai caricato su GitHub e hai aggiunto i test. Ottimo! Il problema è che nessun altro lo conosce.
Documentare il tuo plugin
Tutti i plugin richiedono una buona documentazione. Gli utenti devono sapere cosa fa il plugin, come installarlo, quali impostazioni/modifiche di configurazione importanti sono necessarie e come usarlo. I plugin dovrebbero essere documentati in due luoghi diversi: il file README.md all’interno della tua repo git e un topic dedicato nella categoria Plugin.
Documentazione GitHub
Il file README.md su GitHub è importante poiché viene mostrato di default quando un utente visita la tua repo. Come minimo, il tuo readme dovrebbe includere il titolo del plugin e una breve descrizione. Un readme più completo includerà anche le istruzioni per l’installazione, una descrizione più dettagliata, le istruzioni di base per l’uso, la licenza e (se applicabile) gli screenshot. Se vengono incluse istruzioni aggiuntive nel topic Meta del tuo plugin, assicurati di includere un link al topic.
Esempio di plugin minimamente documentato: Discourse Data Explorer
Esempi di plugin con documentazione più completa: Discourse Solved, Discourse OAuth2 Basic e Discourse Ads.
Modello di README di esempio per il plugin
Assicurati di aggiornare il testo circondato da \u003c\u003e con i dettagli specifici del tuo plugin.
## \u003cTitolo del Plugin\u003e
\u003cDescrizione del Plugin\u003e
## Installazione
Segui la [guida all'installazione dei plugin](https://meta.discourse.org/t/install-a-plugin/19157).
## Come usare
\u003cSpiega come abilitare il plugin, i passaggi di configurazione necessari e come usarlo\u003e
## Screenshot
\u003cIncludi screenshot se necessario per dimostrare l'utilizzo del tuo plugin\u003e
## Leggi di più
\u003cIncludi un link al tuo topic Meta se sono dettagliate informazioni aggiuntive lì\u003e
## Licenza
\u003cIndica la licenza del tuo codice, la maggior parte dei plugin Discourse utilizza MIT\u003e
Documentazione Meta
Mentre la documentazione di GitHub tende ad essere breve e “diretta”, la documentazione Meta è dove puoi condividere tutti i dettagli del tuo plugin e convincere gli utenti del perché dovrebbero usarlo. Come minimo, il tuo topic Meta dovrebbe includere una breve descrizione del plugin e un link alla repo del plugin su GitHub (in modo che gli utenti possano installarlo). Una documentazione più completa includerà anche una descrizione dettagliata con casi d’uso di esempio, istruzioni di utilizzo dettagliate, documentazione di tutte le impostazioni e opzioni di configurazione e screenshot. Gli screenshot sono fondamentali poiché gli utenti vogliono vedere cosa fa il tuo plugin, non solo leggerlo. Un plugin che aggiunge un provider di autenticazione probabilmente necessita solo di 1 screenshot, mentre un plugin che aggiunge una nuova interfaccia o apporta modifiche importanti dovrebbe averne parecchi.
La documentazione Meta tende ad essere più personale di quella di GitHub; ogni autore di plugin ha il proprio stile di documentazione. Qualunque stile tu scelga, assicurati che sia chiaro, facile da leggere e organizzato. Usa le intestazioni come appropriato, annota gli screenshot per spiegare interazioni complesse e assicurati di essere coerente nella formattazione. Evita la tentazione di scrivere un unico grande paragrafo.
Aggiornare la tua documentazione
Dopo aver scritto la documentazione iniziale, è importante mantenerla aggiornata.
Hai aggiunto una nuova funzionalità al plugin? Assicurati di dedicare del tempo per documentarla.
Hai risposto più volte alla stessa domanda? Considera di aggiungere una sezione FAQ al tuo topic Meta.
Problema noto difficile da risolvere? Dettaglialo nel tuo topic in modo che gli utenti sappiano cosa aspettarsi.
Supportare il tuo plugin
Dopo aver pubblicato il tuo plugin e la sua documentazione, gli amministratori di sito che lo trovano utile potrebbero installarlo sui loro siti e iniziare a usarlo. Questo utilizzo richiede un supporto continuo da parte dello sviluppatore del plugin. Dovrai rispondere alle domande che gli amministratori di sito hanno, aiutandoli a usare il tuo plugin. Qualcosa che per te era perfettamente chiaro potrebbe essere poco chiaro per gli altri, quindi vorrai aggiornare il codice e/o la documentazione per chiarirlo. Potresti ricevere richieste di funzionalità, che dovrai decidere se aggiungere o meno.
Infine, Discourse stesso è in costante sviluppo. Sebbene il tuo plugin possa funzionare perfettamente oggi, domani qualcosa potrebbe cambiare e romperlo. Assicurati di rimanere aggiornato sullo sviluppo di Discourse in modo da poter aggiornare il tuo plugin per supportare l’ultima versione di Discourse quando una modifica influisce sul tuo plugin.
Altro nella serie
Parte 1: Plugin Basics
Parte 2: Plugin Outlets
Parte 3: Site Settings
Parte 4: git setup
Parte 5: Admin interfaces
Parte 6: Acceptance tests
Parte 7: Questo topic
Questo documento è controllato tramite versione - suggerisci modifiche su github.
