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:

1. su GitHub, creare un fork del repository nette/docs
2. clonare questo repository sul proprio computer
3. quindi, apportare le modifiche nel ramo appropriato
4. verificare la presenza di spazi extra nel testo utilizzando lo strumento 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 (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.

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.