Sebbene un certo grado di libertà e di variabilità 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 è l’organizzazione del documento in 3 parti:
- Parte iniziale (o intestazione),
- Parte principale (o corpo del documento),
- Parte finale.
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à (ed anche di confidenzialità), ed altri. Un elemento ampiamente diffuso, ma opzionale, è la sezione dei Ringraziamenti, che è 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é sempre presenti sono invece (nell’ordine):
- la lista (o indice) dei capitoli (o delle sezioni, o dei contenuti),
- la lista (o indice) delle figure,
- la lista (o indice) delle tabelle.
Tali liste (o indici) devono essere realizzate mediante riferimenti incrociati, aiutando così 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.
Per ognuna delle tipologie di documento, la parte centrale, o corpo, è univoca e segue le stesse regole. Tale parte infatti ospita il contenuto principale del documento che solitamente è distribuito in più capitoli (o sezioni). Ciascuno capitolo (o sezione) è numerato seguendo una numerazione progressiva. Ciascun capitolo (o sezione) può contenere più sotto-capitoli (o sotto-sezioni), anche su più livelli gerarchici annidati: questi saranno numerati seguendo una numerazione progressiva e gerarchica. Ad esempio:
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
…
Tale numerazione è poi riportata nell’indice dei contenuti, tipicamente seguendo una indentazione basata su livello dei capitoli e dei sotto-capitoli.
Gli articoli scientifici presentano una particolarità relativamente al corpo del documento. È 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 è l’unica che non include la lista dei capitoli (o del contenuto). Un esempio è il seguente: “Il resto del documento è 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 è 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.
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é figure, grafici, tabelle e equazioni, e riferimenti ad essi all’interno del testo. Ciascuno di questi elementi segue regole ben precise.
- Riferimenti bibliografici. 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ù 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ì 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 …” è sbagliato, mentre la forma corretta è “Il riferimento [2] mostra che …”; altrettando “… come evidenziato nei corrispondenti documenti, [4] e [9], ovvero …” è sbagliato, mentre la forma corretta è “… come evidenziato nei corrispondenti documenti, riferimenti [4] e [9], ovvero…”.
- Figure (e Grafici). 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à indice 1.1 (o 1-1), la seconda 1.2 (o 1-2), e così via; la prima figura all’interno del secondo capitolo avrà 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à misurata) e un’unità di misura racchiusa fra parentesi TONDE, come mostrato nella Figura 1.
- Tabelle. Le tabelle seguono esattamente le stesse regole delle figure, con la sola differenza che la didascalia associata deve essere posta SOPRA la tabella.
- Equazioni. Le equazioni sono tipicamente numerate in maniera progressiva senza includere i livelli di gerarchia dei capitoli (o delle sezioni) e possono essere referenziate usando semplicemente il corrispondente indice fra parentesi tonde, come ad esempio “come espresso in (2)”, oppure utilizzando anche la parola “Equazione/i” o “Eq.”: ad esempio, “come indicato dalla Equazione (3)”. Nel caso di riferimento con solo numero fra parentesi tonde, valgono le stesse regole usate per i riferimenti bibliografici, ovvero è obbligatorio usare la parola “Equazione” o “Eq.” nel caso il riferimento sia all’inizio di una frase (o di un inciso).
In linea generale, per quanto riguarda i riferimenti, che siano a sorgenti bibliografiche, figure, grafici, tabelle, equazioni o altri parti del testo del documento, è necessario usare sempre precisi riferimenti incrociati e NON riferimenti generici del tipo “come riportato nella tabella sotto” o “come illustrato sopra”, bensì usando riferimenti quali “come riportato nella Tabella 3.2” o “come illustrato nella Sezione 1.2”, perché ciò rende il documento più chiaro e preciso, ed evita possibili ambiguità.
Per quanto riguarda la parte finale del documento, questa dovrebbe sempre contenere la sezione della Bibliografia (tavolta chiamata Riferimenti, specialmente negli articoli scientifici). Non è comunque rigorosamente necessaria all’interno dei documenti tecnici, benché, qualora possibile, sia fortemente consigliata di includerla perché rende più affidabile il documento e ne aumenta il rigore. Come anticipato, nel caso di articoli scientifici (in riviste o conference), la parte finale può ospitare la sezione (opzionale) dei Ringraziamenti, la quale invece deve essere integrata nella parte iniziale in caso di documenti tecnici o tesi. Un altra sezione opzionale che può essere presente nella parte finale degli articoli scientifici è la sezione dei Finanziamenti, che può essere inserita al posto della sezione Ringraziamenti o assieme ad essa. Un’ultima sezione opzionale che però segue le stesse regola per ciascuna tipologia di documento è la sezione delle Appendici. Possono essere inserite una o più appendici e anch’esse posso includere più sotto-sezioni su più livelli gerarchici. Pertanto la numerazione delle appendici (e delle loro sotto-sezioni) segue la stessa numerazione usata anche per i capitoli (e i loro sotto-capitoli), con l’eccezione che il primo livello di numerazione adotta le lettere maiuscole dell’alfabeto, anzichè i numeri. Ad esempio:
A. Prima appendice
A.1 Primo sotto-capitolo della prima appendice
A.2 Secondo sotto-capitolo della prima appendice
A.2.1 Primo sotto-sotto-capitolo del secondo sotto-capitolo della prima appendice.
B. Seconda appendice
…
In ogni caso, la sezione delle Appendici deve SEMPRE essere inserita DOPO la Bibliografia.
A conclusione di questo articolo, viene inserita la Tabella 1 che illustra in maniera sintetica un riassunto dei vari elementi che possono (o devono) essere inseriti all’interno di un documento, in base alla tipologia del documento.
Tabella 1. Riassunto degli elementi necessari e opzionali per la scrittura di un documento tecnico o scientifico. Gli elementi racchiusi da parentesi tonde indicano elementi opzionali, mentre gli altri sono da considerarsi obbligatori.
| Elemento | Report, manuali, … | Tesi | Articoli scientifici |
|---|---|---|---|
| Parte iniziale | Titolo (Sotto-titolo) Nome autore/i (Email autore/i) (Cronologia versioni) (Parole chiave) (Copyright) (Ringraziamenti) (Dich. responsabilità) Indice capitoli/sezioni Indice delle figure Indice delle tabelle | Titolo Nome autore Nome relatore/i (Ringraziamenti) Indice capitoli/sezioni Indice delle figure Indice delle tabelle | Titolo Nome autore/i Email autore/i Affiliazione autore/i Riassunto Parole chiave |
| Corpo | Capitoli/Sezioni | Capitoli/Sezioni | Capitoli/Sezioni |
| Figure | Numerazione gerarchica progressiva Didascalia SOTTO | Numerazione gerachica progressiva Didascalia SOTTO | Numerazione progressiva (senza gerarchia) Didascalia SOTTO |
| Tabelle | Numerazione gerarchica progressiva Didascalia SOPRA | Numerazione gerarchica progressiva Didascalia SOPRA | Numerazione progressiva (senza gerarchia) Didascalia SOPRA |
| Equazioni | Numerazione progressiva | Numerazione progressiva | Numerazione progressiva |
| Parte finale | (Bibliografia) (Appendice/i) | Bibliografia (Appendice/i) | (Ringraziamenti) (Finanziamenti) Bibliografia (Appendice/i) |