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ì:

1. Su GitHub create un fork del repository nette/docs.
2. Clonate questo repository sul vostro computer.
3. Poi fate le modifiche nel ramo appropriato.
4. Controllate che nel testo non ci siano spazi superflui con lo strumento 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 (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.