Contribuire alla documentazione ******************************* .[perex] Contribuire alla documentazione è una delle attività più preziose, perché aiuta gli altri a comprendere il framework. Come scrivere? .[#toc-how-to-write] ----------------------------------- La documentazione è destinata principalmente a persone che non conoscono l'argomento. Pertanto, deve soddisfare diversi punti importanti: - Iniziare con argomenti semplici e generali. Passare ad argomenti più avanzati alla fine - Cercare di spiegare l'argomento nel modo più chiaro possibile. Ad esempio, provate prima a spiegare l'argomento a un collega. - Fornite solo le informazioni che l'utente ha effettivamente bisogno di conoscere per un determinato argomento. - Assicuratevi che le informazioni siano accurate. Testate ogni codice - Siate concisi: tagliate a metà ciò che scrivete. E poi sentitevi liberi di rifarlo - Usate con parsimonia l'evidenziazione, dai caratteri in grassetto ai riquadri, come ad esempio `.[note]` - Seguire lo [standard di codifica |Coding Standard] nel codice Imparate anche la [sintassi |syntax]. Per avere un'anteprima dell'articolo durante la scrittura, si può usare l'[editor di anteprima |https://editor.nette.org/]. Mutazioni linguistiche .[#toc-language-mutations] ------------------------------------------------- L'inglese è la lingua principale, quindi le modifiche devono essere in inglese. Se l'inglese non è il vostro forte, usate [DeepL Translator |https://www.deepl.com/translator] e altri controlleranno il vostro testo. La traduzione in altre lingue avverrà automaticamente dopo l'approvazione e la messa a punto delle modifiche. Modifiche banali .[#toc-trivial-edits] -------------------------------------- Per contribuire alla documentazione, è necessario avere un account su [GitHub |https://github.com]. Il modo più semplice per apportare piccole modifiche alla documentazione è utilizzare i link alla fine di ogni pagina: - *Mostra su GitHub* apre la versione sorgente della pagina su GitHub. Poi basta premere il pulsante `E` e si può iniziare a modificare (è necessario aver effettuato l'accesso a GitHub). - *Apri anteprima* apre un editor in cui è possibile vedere immediatamente la forma visiva finale Poiché l'[editor di anteprima |https://editor.nette.org/] non ha la possibilità di salvare le modifiche direttamente su GitHub, è necessario copiare il testo sorgente negli appunti (usando il pulsante *Copia negli appunti*) e poi 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, viene creata una cosiddetta richiesta di pull (PR), che può essere ulteriormente modificata. Modifiche più ampie .[#toc-larger-edits] ---------------------------------------- È più opportuno conoscere le basi del lavoro con il sistema di controllo di versione Git, piuttosto che affidarsi esclusivamente all'interfaccia di GitHub. Se non si ha familiarità con Git, si può fare riferimento alla [guida git - the simple |https://rogerdudler.github.io/git-guide/] e prendere in considerazione l'utilizzo di uno dei tanti [client grafici |https://git-scm.com/downloads/guis] disponibili. Modificare la documentazione nel modo seguente: 1) su GitHub, creare 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) [clonare |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] questo repository sul proprio computer 3) quindi, apportare le modifiche nel [ramo appropriato |#Documentation Structure] 4) verificare la presenza di spazi extra nel testo utilizzando lo strumento [Code-Checker |code-checker:] 5) salvare (commit) le modifiche 6) se si è soddisfatti delle modifiche, inviarle su GitHub al proprio fork 7) da lì, inviarle al repository `nette/docs` creando una [pull request|https://help.github.com/articles/creating-a-pull-request] (PR) È frequente ricevere commenti con suggerimenti. Tenere traccia delle modifiche proposte e incorporarle. Aggiungere le modifiche suggerite come nuovi commit e inviarle nuovamente a GitHub. Non creare mai una nuova richiesta di pull solo per modificare una richiesta esistente. Struttura della documentazione .[#toc-documentation-structure] -------------------------------------------------------------- L'intera documentazione si trova su GitHub nel repository [nette/docs |https://github.com/nette/docs]. La versione attuale si trova nel ramo master, mentre le versioni precedenti si trovano nei rami `doc-3.x`, `doc-2.x`. Il contenuto di ogni ramo è suddiviso 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 mutazioni linguistiche (`cs`, `en`, ...) e, opzionalmente, una sottocartella `files` con immagini che possono essere inserite nelle pagine della documentazione.

Contribuire alla documentazione

Contribuire alla documentazione è una delle attività più preziose, perché aiuta gli altri a comprendere il framework.

Come scrivere?

La documentazione è destinata principalmente a persone che non conoscono l'argomento. Pertanto, deve soddisfare diversi punti importanti:

Iniziare con argomenti semplici e generali. Passare ad argomenti più avanzati alla fine
Cercare di spiegare l'argomento nel modo più chiaro possibile. Ad esempio, provate prima a spiegare l'argomento a un collega.
Fornite solo le informazioni che l'utente ha effettivamente bisogno di conoscere per un determinato argomento.
Assicuratevi che le informazioni siano accurate. Testate ogni codice
Siate concisi: tagliate a metà ciò che scrivete. E poi sentitevi liberi di rifarlo
Usate con parsimonia l'evidenziazione, dai caratteri in grassetto ai riquadri, come ad esempio .[note]
Seguire lo standard di codifica nel codice

Imparate anche la sintassi. Per avere un'anteprima dell'articolo durante la scrittura, si può usare l'editor di anteprima.

Mutazioni linguistiche

L'inglese è la lingua principale, quindi le modifiche devono essere in inglese. Se l'inglese non è il vostro forte, usate DeepL Translator e altri controlleranno il vostro testo.

La traduzione in altre lingue avverrà automaticamente dopo l'approvazione e la messa a punto delle modifiche.

Modifiche banali

Per contribuire alla documentazione, è necessario avere un account su GitHub.

Il modo più semplice per apportare piccole modifiche alla documentazione è utilizzare i link alla fine di ogni pagina:

Mostra su GitHub apre la versione sorgente della pagina su GitHub. Poi basta premere il pulsante E e si può iniziare a modificare (è necessario aver effettuato l'accesso a GitHub).
Apri anteprima apre un editor in cui è possibile vedere immediatamente la forma visiva finale

Poiché l'editor di anteprima non ha la possibilità di salvare le modifiche direttamente su GitHub, è necessario copiare il testo sorgente negli appunti (usando il pulsante Copia negli appunti) e poi 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, viene creata una cosiddetta richiesta di pull (PR), che può essere ulteriormente modificata.

Modifiche più ampie

È più opportuno conoscere le basi del lavoro con il sistema di controllo di versione Git, piuttosto che affidarsi esclusivamente all'interfaccia di GitHub. Se non si ha familiarità con Git, si può fare riferimento alla guida git – the simple e prendere in considerazione l'utilizzo di uno dei tanti client grafici disponibili.

Modificare la documentazione nel modo seguente:

su GitHub, creare un fork del repository nette/docs
clonare questo repository sul proprio computer
quindi, apportare le modifiche nel ramo appropriato
verificare la presenza di spazi extra nel testo utilizzando lo strumento Code-Checker
salvare (commit) le modifiche
se si è soddisfatti delle modifiche, inviarle su GitHub al proprio fork
da lì, inviarle al repository nette/docs creando una pull request (PR)

È frequente ricevere commenti con suggerimenti. Tenere traccia delle modifiche proposte e incorporarle. Aggiungere le modifiche suggerite come nuovi commit e inviarle nuovamente a GitHub. Non creare mai una nuova richiesta di pull solo per modificare una richiesta esistente.

Struttura della documentazione

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