Contribuire alla documentazione
*******************************
.[perex]
Contribuire alla documentazione è una delle attività più preziose, perché aiuta gli altri a capire il framework.
Come scrivere?
--------------
La documentazione è pensata anzitutto per chi si avvicina all'argomento per la prima volta. Dovrebbe quindi soddisfare alcuni punti importanti:
- Cominciate dai concetti semplici e generali. Passate ai temi più avanzati solo alla fine.
- Cercate di spiegare l'argomento nel modo più chiaro possibile. Provate per esempio a spiegarlo prima a un collega.
- Fornite solo le informazioni che l'utente ha davvero bisogno di sapere su quell'argomento.
- Verificate che le vostre informazioni siano esatte. Provate ogni pezzo di codice.
- Siate concisi: dimezzate quello che scrivete. E poi fatelo pure di nuovo.
- Usate con parsimonia le evidenziazioni, dal testo in grassetto ai riquadri come `.[note]`.
- Negli esempi di codice rispettate lo [standard di codifica|coding-standard].
Imparate anche la [sintassi |syntax]. Per vedere l'anteprima dell'articolo mentre scrivete potete usare l'[editor di anteprima |https://editor.nette.org/].
Versioni linguistiche
---------------------
La lingua principale è l'inglese, quindi idealmente le vostre modifiche dovrebbero essere in inglese. Se l'inglese non è il vostro forte, usate [DeepL Translator |https://www.deepl.com/translator] e altri rivedranno il vostro testo.
La traduzione nelle altre lingue avverrà automaticamente dopo che la vostra modifica sarà approvata e finalizzata.
Modifiche minime
----------------
Per contribuire alla documentazione dovete avere un account su [GitHub |https://github.com].
Il modo più semplice di fare una piccola modifica nella documentazione è usare i link in fondo a ogni pagina:
- *Mostra su GitHub* apre la versione sorgente della pagina su GitHub. Poi basta premere il tasto `E` per cominciare a modificare (dovete essere connessi a GitHub).
- *Apri anteprima* apre un editor in cui vedete subito l'aspetto visivo finale.
Poiché l'[editor di anteprima |https://editor.nette.org/] non sa salvare le modifiche direttamente su GitHub, dopo aver finito di modificare dovete copiare il testo sorgente negli appunti (con il pulsante *Copia negli appunti*) e poi incollarlo nell'editor su GitHub. Sotto il campo di modifica c'è un modulo di invio. Qui non dimenticate di riassumere brevemente e spiegare il motivo della vostra modifica. Dopo l'invio viene creata una pull request (PR), che si può modificare ulteriormente.
Modifiche più ampie
-------------------
Invece di affidarvi solo all'interfaccia di GitHub, è meglio conoscere le basi del lavoro con il sistema di versionamento Git. Se non conoscete Git, potete consultare [git - the simple guide |https://rogerdudler.github.io/git-guide/] e considerare l'uso di uno dei tanti [client grafici |https://git-scm.com/downloads/guis] disponibili.
Modificate la documentazione così:
1) Su GitHub create un [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] del repository [nette/docs |https://github.com/nette/docs].
2) [Clonate |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] questo repository sul vostro computer.
3) Poi fate le modifiche nel [ramo appropriato |#Struttura della documentazione].
4) Controllate che nel testo non ci siano spazi superflui con lo strumento [Code-Checker |tools:code-checker].
5) Salvate (commit) le modifiche.
6) Se siete soddisfatti delle modifiche, inviatele (push) su GitHub nel vostro fork.
7) Da lì proponetele al repository `nette/docs` creando una [pull request|https://help.github.com/articles/creating-a-pull-request] (PR).
È normale ricevere commenti con dei suggerimenti. Seguite le modifiche proposte e incorporatele. Aggiungete le modifiche proposte come nuovi commit e inviatele di nuovo su GitHub. Non create mai una nuova pull request solo per modificarne una esistente.
Struttura della documentazione
------------------------------
Tutta la documentazione si trova su GitHub nel repository [nette/docs |https://github.com/nette/docs]. La versione attuale è nel ramo `master`, mentre le versioni più vecchie stanno 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. Per esempio `application/` corrisponde a `https://doc.nette.org/en/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 le immagini che si possono inserire nelle pagine della documentazione.
Contribuire alla documentazione
Contribuire alla documentazione è una delle attività più preziose, perché aiuta gli altri a capire il
framework.
Come scrivere?
La documentazione è pensata anzitutto per chi si avvicina all'argomento per la prima volta. Dovrebbe quindi soddisfare alcuni
punti importanti:
- Cominciate dai concetti semplici e generali. Passate ai temi più avanzati solo alla fine.
- Cercate di spiegare l'argomento nel modo più chiaro possibile. Provate per esempio a spiegarlo prima a un collega.
- Fornite solo le informazioni che l'utente ha davvero bisogno di sapere su quell'argomento.
- Verificate che le vostre informazioni siano esatte. Provate ogni pezzo di codice.
- Siate concisi: dimezzate quello che scrivete. E poi fatelo pure di nuovo.
- Usate con parsimonia le evidenziazioni, dal testo in grassetto ai riquadri come
.[note].
- Negli esempi di codice rispettate lo standard di
codifica.
Imparate anche la sintassi. Per vedere l'anteprima dell'articolo
mentre scrivete potete usare l'editor di anteprima.
Versioni linguistiche
La lingua principale è l'inglese, quindi idealmente le vostre modifiche dovrebbero essere in inglese. Se l'inglese non è il
vostro forte, usate DeepL Translator e altri rivedranno il vostro testo.
La traduzione nelle altre lingue avverrà automaticamente dopo che la vostra modifica sarà approvata e finalizzata.
Modifiche minime
Per contribuire alla documentazione dovete avere un account su GitHub.
Il modo più semplice di fare una piccola modifica nella documentazione è usare i link in fondo a ogni pagina:
- Mostra su GitHub apre la versione sorgente della pagina su GitHub. Poi basta premere il tasto
E per
cominciare a modificare (dovete essere connessi a GitHub).
- Apri anteprima apre un editor in cui vedete subito l'aspetto visivo finale.
Poiché l'editor di anteprima non sa salvare le modifiche direttamente su GitHub, dopo
aver finito di modificare dovete copiare il testo sorgente negli appunti (con il pulsante Copia negli appunti) e poi
incollarlo nell'editor su GitHub. Sotto il campo di modifica c'è un modulo di invio. Qui non dimenticate di riassumere brevemente
e spiegare il motivo della vostra modifica. Dopo l'invio viene creata una pull request (PR), che si può modificare
ulteriormente.
Modifiche più ampie
Invece di affidarvi solo all'interfaccia di GitHub, è meglio conoscere le basi del lavoro con il sistema di versionamento Git.
Se non conoscete Git, potete consultare git – the simple guide e
considerare l'uso di uno dei tanti client grafici disponibili.
Modificate la documentazione così:
- Su GitHub create un fork del
repository nette/docs.
- Clonate questo
repository sul vostro computer.
- Poi fate le modifiche nel ramo appropriato.
- Controllate che nel testo non ci siano spazi superflui con lo strumento Code-Checker.
- Salvate (commit) le modifiche.
- Se siete soddisfatti delle modifiche, inviatele (push) su GitHub nel vostro fork.
- Da lì proponetele al repository
nette/docs creando una pull request (PR).
È normale ricevere commenti con dei suggerimenti. Seguite le modifiche proposte e incorporatele. Aggiungete le modifiche
proposte come nuovi commit e inviatele di nuovo su GitHub. Non create mai una nuova pull request solo per modificarne una
esistente.
Struttura della documentazione
Tutta la documentazione si trova su GitHub nel repository nette/docs. La versione
attuale è nel ramo master, mentre le versioni più vecchie stanno 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. Per esempio
application/ corrisponde a https://doc.nette.org/en/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 le immagini che si
possono inserire nelle pagine della documentazione.