Linee guida sul contenuto
Questo documento delinea cosa si dovrebbe includere nella documentazione ufficiale. Di seguito, sono riportati alcuni principi e raccomandazioni per scrivere contenuti accessibili.
Vogliamo raggiungere due obiettivi:
Mostra empatia con i nostri utenti. Dovremmo scrivere in un modo che renda facile per loro imparare dalla documentazione.
Scrivere un manuale di riferimento completo. Il nostro obiettivo qui non è insegnare i fondamenti della programmazione. Piuttosto, il nostro obiettivo è fornire un riferimento su come funzionano le funzionalità di Godot.
Linee guida e principi
Di seguito sono riportate le linee guida che dovremmo cercare di seguire. Non si tratta di regole rigide, però: a volte, un argomento richiederà di infrangerne una o più. Ad ogni modo, dovremmo impegnarci a realizzare i due obiettivi elencati in precedenza.
Scrivere una documentazione completa e accessibile
Una funzionalità non esiste se non è documentata. Se un utente non riesce a trovare informazioni su una funzionalità e sul suo funzionamento, per lui non esiste. Dobbiamo assicurarci di trattare tutto ciò che fa Godot.
Nota
Quando si aggiunge o si aggiorna una funzionalità del motore, il team di documentazione deve esserne a conoscenza. I collaboratori dovrebbero aprire una segnalazione sul repository godot-docs dopo il merge del loro lavoro e necessita di documentazione.
Fare del proprio meglio per mantenere i documenti al di sotto delle 1000 parole. Se una pagina supera questa soglia, considerare di dividerla in due parti. Limitare le dimensioni delle pagine ci obbliga a scrivere in modo conciso e a suddividere i grandi documenti in modo che ogni pagina si concentri su un argomento specifico.
Ogni pagina o sezione di una pagina dovrebbe indicare chiaramente quale problema affronta e cosa insegnerà all'utente. Gli utenti devono sapere se stanno leggendo la guida corretta per risolvere i problemi che stanno riscontrando. Ad esempio, invece di scrivere il titolo "Segnali", si consideri di scrivere "Reagire ai cambiamenti con i segnali". Il secondo titolo rende lo scopo dei segnali più chiaro.
Nota
I titoli di sezione lunghi risultano in voci lunghe nel menu laterale, il che può rendere la navigazione macchinosa. Cercare di mantenere i titoli lunghi al massimo cinque parole.
Se la pagina presuppone una conoscenza specifica di altre funzionalità di Godot, menzionarla e inserire un collegamento alla documentazione corrispondente. Ad esempio, una pagina sulla fisica potrebbe utilizzare i segnali, nel qual caso potreste specificare che il tutorial sui segnali è un prerequisito. È concesso anche collegare ad altri siti web per prerequisiti che vanno oltre l'ambito della documentazione. Ad esempio, si potrebbe collegare a un'introduzione alla programmazione nella guida introduttiva, oppure a un sito web che insegna teorie matematiche nella sezione di matematica.
Limitare il carico cognitivo
Limit the cognitive load required to read the documentation. The simpler and more explicit language we use, the more efficient it becomes for people to learn. You can do so by:
Introdurre solo un nuovo concetto alla volta, qualora sia possibile.
Utilizzare un inglese semplice, come raccomandiamo nelle nostre linee guida di scrittura.
Includendo uno o più esempi di utilizzo concreto. È preferito un esempio concreto a uno che usa nomi come
foo,barobaz.
Mentre molte persone potrebbero comprendere un linguaggio più complesso ed esempi astratti, se ne perderanno altre. Una scrittura comprensibile ed esempi pratici sono vantaggiosi per tutti.
Cercare sempre di mettersi nei panni dell'utente. Quando comprendiamo qualcosa a fondo, ci diventa ovvio. Potremmo non pensare ai dettagli rilevanti per un nuovo arrivato, ma una buona documentazione incontra gli utenti esattamente dove si trovano. Dovremmo spiegare le capacità o gli usi previsti di ogni funzionalità con il linguaggio più semplice possibile.
Try to remember what you first needed to know when learning about the feature or concept. What new terms did you need to learn? What confused you? What was the hardest to grasp? You will want users to review your work, and we recommend you practice explaining the feature before writing about it.
Nota
I fondamenti della programmazione sono un prerequisito per utilizzare un motore complesso come Godot. Parlare di variabili, funzioni o classi è accettabile. Ma dovremmo preferire un linguaggio semplice, anziché una terminologia specifica come "meta-programmazione". Se si devono usare termini precisi, assicurarsi di definirli.