{"id":575,"date":"2023-12-08T17:54:15","date_gmt":"2023-12-08T16:54:15","guid":{"rendered":"https:\/\/people.unipi.it\/luca_crocetti\/?p=575"},"modified":"2023-12-09T09:40:31","modified_gmt":"2023-12-09T08:40:31","slug":"doc-tecn","status":"publish","type":"post","link":"https:\/\/people.unipi.it\/luca_crocetti\/it\/doc-tecn\/","title":{"rendered":"Documentazione tecnica e scientifica: regole principali e suggerimenti"},"content":{"rendered":"\n
Sebbene un certo grado di libert\u00e0 e di variabilit\u00e0 siano concessi e riscontrabili, la scrittura e l’elaborazione della documentazione tecnica tipicamente segue delle regole universalmente condivise ed apprezzate che possono essere usate come punto di riferimento. Tali regole si applicano a documenti sia di carattere tecnico (come report e manuali utenti), sia di carattere scientifico (come tesi e articoli scientifici in riviste o conferenze). La prima fra tutte \u00e8 l’organizzazione del documento in 3 parti:<\/p>\n\n\n\n
\n
Parte iniziale (o intestazione),<\/li>\n\n\n\n
Parte principale (o corpo del documento),<\/li>\n\n\n\n
Parte finale.<\/li>\n<\/ol>\n\n\n\n
La parte inziale (o intestazione) contiene i dati saliente e di riferimento del documento, quali titolo, eventuale sotto-titolo e nome dell’autore (o degli autori) ed eventualmente i suoi (i loro) dati di riferimento come l’indirizzo mail e\/o l’affiliazione (ente\/azienda di appartenenza). In caso di documentazione tecnica, in questa parte possono anche essere inserite elementi come la cronologia delle versioni del documento in forma tabellare (e.g., v0.1 prima bozza, autore XX, …), informazioni sul copyright, dichiarazioni di responsabilit\u00e0 (ed anche di confidenzialit\u00e0), ed altri. Un elemento ampiamente diffuso, ma opzionale, \u00e8 la sezione dei Ringraziamenti, che \u00e8 inserita in questa parte nel caso di documenti tecnici o tesi, mentre negli articoli scientifici tale sezione, sempre opzionale, si trova nella parte finale del documento. Elementi di fondamentale importanza e pressocch\u00e9 sempre presenti sono invece (nell’ordine):<\/p>\n\n\n\n
\n
la lista<\/strong> (o indice<\/strong>) dei capitoli<\/strong> (o delle sezioni, o dei contenuti<\/strong>),<\/li>\n\n\n\n
la lista <\/strong>(o indice<\/strong>) delle figure<\/strong>,<\/li>\n\n\n\n
la lista <\/strong>(o indice<\/strong>) delle tabelle<\/strong>.<\/li>\n<\/ul>\n\n\n\n
Tali liste (o indici) devono essere realizzate mediante riferimenti incrociati, aiutando cos\u00ec il lettore nella comprensione della struttura del documento e fornendogli collegamenti rapidi ai molteplici punti del documento. Fanno eccezioni gli articoli scientifici in cui tali indici non sono presenti, ma in cui trovano posto sezioni obbligatorie quali il Riassunto (o Sommario, o Abstract, in inglese) e la lista delle parole chiave, che sono indicazioni sugli argomenti cardine su cui si base il lavoro presentato.<\/p>\n\n\n\n
Per ognuna delle tipologie di documento, la parte centrale, o corpo, \u00e8 univoca e segue le stesse regole. Tale parte infatti ospita il contenuto principale del documento che solitamente \u00e8 distribuito in pi\u00f9 capitoli (o sezioni). Ciascuno capitolo (o sezione) \u00e8 numerato seguendo una numerazione progressiva. Ciascun capitolo (o sezione) pu\u00f2 contenere pi\u00f9 sotto-capitoli (o sotto-sezioni), anche su pi\u00f9 livelli gerarchici annidati: questi saranno numerati seguendo una numerazione progressiva e gerarchica. Ad esempio:<\/p>\n\n\n\n
1. Primo capitolo 1.1 Primo sotto-capitolo del primo capitolo 1.2 Secondo sotto-capitolo del primo capitolo 1.2.1 Primo sotto-sotto-capitolo (o capitolo di terzo livello) del secondo sotto-capitolo (o capitolo di secondo livello) del primo capitolo 1.3 Terzo sotto-capitolo del primo capitolo 2. Secondo capitolo …<\/p>\n\n\n\n
Tale numerazione \u00e8 poi riportata nell’indice dei contenuti, tipicamente seguendo una indentazione basata su livello dei capitoli e dei sotto-capitoli.<\/p>\n\n\n\n
Gli articoli scientifici presentano una particolarit\u00e0 relativamente al corpo del documento. \u00c8 prassi comune e ampiamente diffusa che il primo capitolo sia denominato Introduzione e che nella sua parte conclusiva sia riportata la struttura e il contenuto degli altri capitoli. Infatti tale tipologia \u00e8 l’unica che non include la lista dei capitoli (o del contenuto). Un esempio \u00e8 il seguente: “Il resto del documento \u00e8 organizzato come segue: il Capitolo 2 descrive …; nel Capitolo 3 sono illustrati …; nel Capitolo 4 vengono riportarti i risultati; infine, il Capitolo 5 presenta le conclusioni di questo lavoro.” Analogamente, solitamente l’ultimo capitolo \u00e8 denominato Conclusioni (o Discussione, oppure sono inclusi entrambi, usando il capitolo Conclusioni come ultimo capitolo). Questo, o questi, sono solitamente preceduto dal capitolo dei risultati e per questo tipicamente chiamato Risultati.<\/p>\n\n\n\n
A supporto del contenuto del documento, distribuito nei vari capitoli e sotto-capitoli, possono essere inseriti riferimenti ad altri documenti (che faranno parte della sezione Bibliografia, in ogni caso inclusa nella parte finale del documento), nonch\u00e9 figure, grafici, tabelle e equazioni, e riferimenti ad essi all’interno del testo. Ciascuno di questi elementi segue regole ben precise.<\/p>\n\n\n\n
\n
Riferimenti <\/strong>bibliografici<\/strong>. Sono inseriti all’interno del testo, al fine di citare il corrispondente documento presente nella bibliografia, utilizzando le parentesi quadre: ad esempio, “[3]”. Tipicamente viene utilizzato il solo numero di riferimento (o un intervallo di numeri, qualora si faccia riferimento ad pi\u00f9 sorgenti bibliografiche in ordine sequenziale, ad esempio “[4-9]” per indicare tutti i documenti bibliografici dal [4] al [9], estremi inclusi). Pertanto, tipicamente in un documenti si potranno trovare frasi come “In [1] viene specificato che. ..”, oppure, “… come indicato in [7].”, e cos\u00ec via. Non si dovrebbe mai usare la forma del tipo “Nel riferimento [2] …”, a meno che il numero di riferimento non sia all’inizio di una frase (o di un inciso). Ad esempio, “[2] mostra che …” \u00e8 sbagliato, mentre la forma corretta \u00e8 “Il riferimento [2] mostra che …”; altrettando “… come evidenziato nei corrispondenti documenti, [4] e [9], ovvero …” \u00e8 sbagliato, mentre la forma corretta \u00e8 “… come evidenziato nei corrispondenti documenti, riferimenti [4] e [9], ovvero…”.<\/li>\n\n\n\n
Figure<\/strong> (e Grafici<\/strong>). Tutte le figure devono essere numerate ed essere corredate di una didascalia che deve essere posta SOTTO la figura. La didascalia ha lo scopo di indicare sinteticamente il significato della figura, mentre la numerazione delle figure deve essere progressiva e gerarchica, seguendo la numerazioni dei capitoli (solo di primo livello). Ad esempio, la prima figura all’interno del primo capitolo avr\u00e0 indice 1.1 (o 1-1), la seconda 1.2 (o 1-2), e cos\u00ec via; la prima figura all’interno del secondo capitolo avr\u00e0 indice 2.1 (o 2-1), anche nel caso essa sia la prima figura dell’intero documento. Fanno eccezione gli articoli scientifici, nel cui caso le figure seguono una numerazione puramente progressiva senza connessioni con la gerarchia dei capitoli. Inoltre, tutte le figure devono essere referenziate nel testo obbligatoriamente prima del loro inserimento, e potranno essere liberamente referenziate in altri parti del documento senza limitazioni. Per referenziare una figura si usano i riferimenti incrociati nella forma “La Figura 1.2 mostra …”, oppure “come mostrato in Fig. 1.2”. I grafici sono un tipo particolare di figure caratterizzate dalla presenza di assi di rappresentazione. Questi devono seguire tutte le regole sopra indicate per le figure e in aggiunta ad ogni asse deve essere associata una etichetta (relativa alla quantit\u00e0 misurata) e un’unit\u00e0 di misura racchiusa fra parentesi TONDE, come mostrato nella Figura 1.<\/li>\n<\/ul>\n\n\n\n
![\"\"](\"https:\/\/people.unipi.it\/luca_crocetti\/wp-content\/uploads\/sites\/658\/2023\/12\/128_arash_sbox_power.png\")
<\/a>