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 ne sa nulla.
Documentare il tuo plugin
Tutti i plugin richiedono una buona documentazione. Gli utenti devono sapere cosa fa il plugin, come installarlo, quali impostazioni o modifiche di configurazione sono importanti e come utilizzarlo. I plugin dovrebbero essere documentati in due posizioni diverse: il file README.md all’interno del tuo repository git e un argomento dedicato nella categoria Customization > Plugin.
Documentazione su GitHub
Il file README.md su GitHub è importante perché viene visualizzato di default quando un utente visita il tuo repository. Al 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, istruzioni di base per l’uso, la licenza e (se applicabile) screenshot. Se istruzioni aggiuntive sono incluse nell’argomento Meta del tuo plugin, assicurati di includere un link all’argomento.
Esempio di un plugin documentato al minimo: Discourse Data Explorer
Esempi di plugin con documentazione più completa: Discourse Solved, Discourse OAuth2 Basic e Discourse Ads.
Modello README di esempio per plugin
Assicurati di aggiornare il testo racchiuso tra < > con i dettagli specifici del tuo plugin.
## <Titolo Plugin>
<Descrizione Plugin>
## Installazione
Segui la [guida all'installazione dei plugin](https://meta.discourse.org/t/install-a-plugin/19157).
## Come usare
<Spiega come abilitare il plugin, i passaggi di configurazione necessari e come utilizzarlo>
## Screenshot
<Includi screenshot se necessario per dimostrare l'uso del tuo plugin>
## Approfondimenti
<Includi un link al tuo argomento Meta se lì sono dettagliate informazioni aggiuntive>
## Licenza
<Indica la licenza del tuo codice, la maggior parte dei plugin Discourse usa la MIT>
Documentazione su Meta
Mentre la documentazione su GitHub tende ad essere breve e “sintetica”, la documentazione su Meta è dove puoi condividere tutti i dettagli del tuo plugin e convincere gli utenti del perché dovrebbero usarlo. Al minimo, il tuo argomento Meta dovrebbe includere una breve descrizione del plugin e un link al repository del plugin su GitHub (così gli utenti possono installarlo). Una documentazione più completa includerà anche una descrizione dettagliata con esempi di casi d’uso, istruzioni dettagliate per l’uso, documentazione di tutte le impostazioni e opzioni di configurazione, e screenshot. Gli screenshot sono fondamentali perché gli utenti vogliono vedere cosa fa il tuo plugin, non solo leggerne la descrizione. Un plugin che aggiunge un provider di autenticazione probabilmente avrà bisogno di solo 1 screenshot, mentre un plugin che aggiunge una nuova interfaccia o apporta modifiche significative dovrebbe averne diversi.
La documentazione su Meta tende ad essere più personale rispetto a quella su 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 dove appropriato, annota gli screenshot per spiegare interazioni complesse e assicurati di essere coerente nella formattazione. Evita la tentazione di scrivere un unico paragrafo gigante.
Aggiornare la tua documentazione
Dopo aver scritto la tua documentazione iniziale, è importante mantenerla aggiornata.
Hai aggiunto una nuova funzionalità al plugin? Assicurati di dedicare del tempo per documentarla.
Hai risposto alla stessa domanda più volte? Considera l’aggiunta di una sezione FAQ al tuo argomento Meta.
C’è un problema noto che è complicato da risolvere? Dettaglialo nel tuo argomento così gli utenti sapranno cosa aspettarsi.
Supportare il tuo plugin
Dopo aver pubblicato il tuo plugin e la sua documentazione, gli amministratori di sito che lo troveranno utile potrebbero installarlo sul loro sito e iniziare a usarlo. Questo utilizzo richiede un supporto continuo da parte dello sviluppatore del plugin. Dovrai rispondere alle domande degli amministratori di sito, aiutandoli a utilizzare il tuo plugin. Qualcosa che aveva perfettamente senso per te 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 che lo rompe. Assicurati di stare al passo con lo sviluppo di Discourse in modo da poter aggiornare il tuo plugin per supportare l’ultima versione di Discourse quando una modifica lo riguarda.
Altri articoli della serie
Parte 1: Nozioni di base sui plugin
Parte 2: Plugin Outlets
Parte 3: Impostazioni del sito
Parte 4: Configurazione git
Parte 5: Interfacce di amministrazione
Parte 6: Test di accettazione
Parte 7: Questo argomento
Questo documento è sotto controllo versione - suggerisci modifiche su github.
