Come contribuire alla documentazione

Contribuire alla documentazione è una delle attività più gratificanti, poiché aiutate gli altri a comprendere il framework.

Come scrivere?

La documentazione è destinata principalmente alle persone che si avvicinano all'argomento. Pertanto, dovrebbe soddisfare diversi punti importanti:

• Iniziate dal semplice e generale. Passate ad argomenti più avanzati solo alla fine.
• Cercate di spiegare la cosa nel miglior modo possibile. Provate, ad esempio, a spiegare prima l'argomento a un collega.
• Fornite solo le informazioni di cui l'utente ha effettivamente bisogno per l'argomento specifico.
• Verificate che le vostre informazioni siano effettivamente vere. Testate ogni codice.
• Siate concisi – dimezzate ciò che scrivete. E poi, se necessario, ancora una volta.
• Risparmiate sugli evidenziatori di ogni tipo, dal grassetto alle cornici come .[note].
• Nel codice, rispettate lo Standard di codifica.

Imparate anche la sintassi. Per visualizzare l'anteprima dell'articolo durante la scrittura, potete utilizzare l'editor con anteprima.

Versioni linguistiche

La lingua principale è l'inglese, quindi le vostre modifiche dovrebbero essere sia in ceco che in inglese. Se l'inglese non è il vostro forte, utilizzate DeepL Translator e gli altri controlleranno il testo per voi.

La traduzione nelle altre lingue verrà eseguita automaticamente dopo l'approvazione e la messa a punto della vostra modifica.

Modifiche triviali

Per contribuire alla documentazione è indispensabile avere un account su GitHub.

Il modo più semplice per apportare una piccola modifica alla documentazione è utilizzare i link alla fine di ogni pagina:

• Mostra su GitHub apre la versione sorgente della pagina data su GitHub. Successivamente, è sufficiente premere il pulsante E e potete iniziare a modificare (è necessario essere loggati su GitHub).
• Apri anteprima apre l'editor, dove vedete subito anche l'aspetto visivo risultante.

Poiché l'editor con anteprima non ha la possibilità di salvare le modifiche direttamente su GitHub, è necessario, dopo aver completato le modifiche, copiare il testo sorgente negli appunti (con il pulsante Copy to clipboard) e quindi incollarlo nell'editor su GitHub. Sotto il campo di modifica c'è un modulo per l'invio. Qui non dimenticate di riassumere brevemente e spiegare il motivo della vostra modifica. Dopo l'invio, verrà creata una cosiddetta pull request (PR), che potrà essere ulteriormente modificata.

Modifiche più grandi

Più appropriato che utilizzare l'interfaccia di GitHub, è essere familiari con le basi del lavoro con il sistema di versionamento Git. Se non conoscete il lavoro con Git, potete consultare la guida git – the simple guide ed eventualmente utilizzare uno dei tanti client grafici.

Modificate la documentazione in questo modo:

1. su GitHub, create un fork del repository nette/docs
2. clonate questo repository sul vostro computer
3. successivamente, nel ramo appropriato, apportate le modifiche
4. controllate gli spazi superflui nel testo tramite lo strumento Code-Checker
5. salvate (committate) le modifiche
6. se siete soddisfatti delle modifiche, inviatele (push) su GitHub al vostro fork
7. da lì, inviatele al repository nette/docs creando una pull request (PR)

È comune ricevere commenti con suggerimenti. Seguite le modifiche proposte e integrateli. Aggiungete le modifiche proposte come nuovi commit e inviatele nuovamente su GitHub. Non create mai una nuova pull request per modificare una pull request esistente.

Struttura della documentazione

L'intera documentazione si trova su GitHub nel repository nette/docs. La versione attuale è nel master, le versioni precedenti si trovano in rami come doc-3.x, doc-2.x.

Il contenuto di ogni ramo è diviso in cartelle principali che rappresentano le singole aree della documentazione. Ad esempio, application/ corrisponde a https://doc.nette.org/cs/application, latte/ corrisponde a https://latte.nette.org ecc. Ognuna di queste cartelle contiene sottocartelle che rappresentano le versioni linguistiche (cs, en, …) ed eventualmente una sottocartella files con immagini che possono essere inserite nelle pagine della documentazione.