Linee guida per la stesura di una relazione tecnica

Linee guida per la stesura di una
relazione tecnica
Autore: Samuele Crivellaro – A.s. 2014-2015
Presentiamo qui di seguito alcune linee guida per la stesura di una relazione tecnica, con una
particolare attenzione rivolta al settore elettronico. Ovviamente va tenuto presente che le
indicazioni fornite hanno carattere indicativo e non prescrittivo: sono suggerimenti che il tecnico
deve usare assieme al proprio buon senso!
Indice
1.
La struttura della relazione ........................................................................................................... 1
1.1
L’intestazione ................................................................................................................... 1
1.2
L’indice ............................................................................................................................. 2
1.3
Il sommario e l’Introduzione ............................................................................................ 2
1.4
Il corpo centrale della relazione....................................................................................... 3
1.5
Le conclusioni ................................................................................................................... 3
1.6
Le appendici ..................................................................................................................... 4
1.7
Figure, tavole, tabelle, grafici ed equazioni ..................................................................... 4
1.8
La bibliografia ................................................................................................................... 5
2. Consigli per la composizione......................................................................................................... 6
3. Osservazioni sull’impaginazione ................................................................................................... 7
Bibliografia ........................................................................................................................................... 9
1. La struttura della relazione
1.1 L’intestazione
Ogni relazione deve prevedere un’intestazione utile ad individuare immediatamente alcuni suoi
caratteri salienti. In particolare devono essere generalmente presenti:
 Titolo. Deve essere sintetico e significativo, in modo da permettere al lettore di individuare
immediatamente e con precisione l’oggetto della relazione.
 Autore (prima il nome e poi il cognome)
 Data di redazione
A tali informazioni possono esserne aggiunte altre, per esempio:
 Nome e cognome del docente (o dei docenti)
 Classe di appartenenza
 Nome dell’istituto (p. es. “ITIS C. Zuccante – Mestre”)
1
L’intestazione può essere inserita all’inizio della prima pagina della relazione (se il documento è
composto di poche pagine) o può occupare l’intera prima pagina.
1.2 L’indice
L’indice deve essere preferibilmente inserito all’inizio del documento, perché permette al
lettore di individuare immediatamente le sezioni principali della relazione, scegliendo
eventualmente di “saltare” direttamente alla sezione di interesse. I numeri di pagina associati a
capitoli e paragrafi è meglio se vengono allineati a destra, così da poter essere individuati più
facilmente (cfr. l’indice del presente documento).
Per velocizzare il processo di compilazione dell’indice ogni word processor moderno mette a
disposizione delle funzioni automatiche. Il loro utilizzo impone un lavoro preliminare di
impostazione degli stili, ma permette in realtà di risparmiare molto tempo, soprattutto se si
apportano modifiche al documento dopo aver redatto l’indice (cfr. capitolo 3 per maggiori
dettagli).
1.3 Il sommario e l’Introduzione
Il sommario (non sempre indispensabile) deve fornire in poche righe informazioni generali sul
documento, così da permettere al lettore di capire se questo è di suo interesse. Per esempio, nel
caso di un progetto, possono essere inserite le specifiche dello stesso. Può essere inserito subito
dopo l’intestazione (prima dell’indice) o subito dopo l’indice.
Nell’introduzione si devono inserire tutte le nozioni preliminari per inquadrare il problema
generale trattato. Nel caso di un progetto è utile, per esempio, inserire uno schema a blocchi del
sistema spiegando brevemente la funzione delle varie parti. Può anche essere utile riportare più di
uno schema a blocchi; uno generale per il sistema ed altri, eventuali, per illustrare in maggior
dettaglio le sue singole parti. In Figura 1, per esempio, è riportato uno schema a blocchi
semplificato di un oscilloscopio, che può essere utile per una prima comprensione dello
strumento, mentre in Figura 2 è riportato uno schema più sofisticato del medesimo strumento,
indispensabile per una sua comprensione più approfondita.
Figura 1. Schema a blocchi semplificato di un
oscilloscopio
Figura 2. Schema a blocchi completo di un
oscilloscopio
2
1.4 Il corpo centrale della relazione
In questa sezione devono essere riportate tutte le considerazioni dettagliate relative al tema
trattato. Se, per esempio, si sta redigendo la relazione di un progetto devono essere presenti:
 le scelte circuitali compiute (e quelle eventualmente scartate) corredate di opportuni schemi
circuitali;
 il dimensionamento dei dispositivi utilizzati;
 il codice per microcontrollore o per microprocessore eventualmente utilizzato (e
debitamente commentato!);
 i risultati sperimentali, ovvero tutte le misure che si sono effettuate sul prodotto finale e che
ne comprovano la piena funzionalità; in particolare devono essere inserite le tabelle delle
misure effettuate ed eventuali grafici;
 immagini del prodotto finito;
 osservazioni conclusive
Per la relazione di un processo di misura, invece, si possono prevedere le seguenti sezioni:
 obiettivo ed oggetto della misura;
 apparecchi utilizzati;
 componenti utilizzati;
 schema circuitale;
 schema di montaggio;
 descrizione del processo di misura;
 calcoli preliminari;
 misure effettuate;
 tabelle di confronto tra i valori calcolati e quelli misurati;
 grafici;
 simulazioni;
 osservazioni analitiche dei risultati ottenuti in relazione all’obiettivo della prova;
 osservazioni conclusive.
Ancora una volta è importante sottolineare che le parti appena indicate non devono essere
inserite tutte obbligatoriamente, né l’ordine delle parti deve essere rigorosamente quello indicato.
Gli schemi elettrici completi, i PCB, gli schemi di disposizione dei componenti sulla scheda
elettronica e in generale tutte le tavole grafiche è preferibile vengano inserite in appendice, per
non appesantire la lettura. Solitamente devono occupare un’intera pagina (foglio A4) ed essere
disposte in orizzontale col bordo inferiore a destra.
1.5 Le conclusioni
Ogni relazione è opportuno contenga una seppur breve conclusione nella quale vanno inserite
considerazioni di carattere generale. In relazioni relative a processi di misura, per esempio,
possono essere messe in rilievo misure anomale che si sono raccolte; naturalmente è perlomeno
opportuno tentare di spiegare tali anomalie. In relazioni conclusive di un progetto possono invece
essere messi in evidenza i punti forti e quelli deboli del progetto presentato, così da permetterne,
fra l’altro, ulteriori analisi e sviluppi da parte di altri tecnici. In ogni caso è opportuno fare un
confronto tra i risultati ottenuti e gli obiettivi inizialmente prefissati.
3
1.6 Le appendici
Le appendici devono contenere tutte quelle parti che, se inserite nel corpo della relazione, ne
appesentirebbero notevolmente la lettura. Tipiche sezioni che si trovano nelle appendici delle
relazioni tecniche sono:
 tavole grafiche (schemi elettrici, PCB, schemi di disposizione componenti…);
 trattazioni teoriche approfondite ma non indispensabili alla comprensione del corpo centrale
del documento;
 datasheet (o, meglio, stralci di datasheet); poiché, grazie alla larga diffusione di internet, i
fogli tecnici sono facilmente accessibili a tutti, è generalmente sconsigliato il loro
inserimento e si preferisce invece riportarne solo le parti utili alla comprensione della
relazione (eventualmente nel corpo del documento, invece che in appendice);
 codici di programmi che presentano un’estensione di più di trenta o quaranta righe (e che
devono sempre essere commentati);
 tabelle di misure (specialmente se particolarmente lunghe, altrimenti è possibile inserirle nel
corpo del documento);
 grafici (ma alcuni è meglio inserirli nel corpo del testo).
1.7 Figure, tavole, tabelle, grafici ed equazioni
Ecco alcuni consigli per l’inserimento di questi indispensabili “complementi” di una relazione
tecnica.
Le figure devono sempre essere numerate, avere possibilmente una didascalia e ad esse si deve
fare esplicito riferimento all’interno del testo.
Le tavole occupano generalmente un’intera pagina e devono sempre avere, in basso a destra, il
cartiglio, un riquadro che contenga le informazioni salienti, quali, in particolare: titolo del disegno,
nome dell’autore, data di realizzazione, numero della revisione e numero del foglio qualora, per
rappresentare il disegno, si siano utilizzati più fogli. In Figura 3 si vede un esempio di cartiglio
tracciato col programma Kicad eeschema.
Figura 3. Esempio di cartiglio tracciato da Kicad eeschema
Le tabelle, anch’esse numerate e dotate di didascalia, sono estremamente frequenti nella
relazioni tecniche perché documentano in maniera precisa il lavoro svolto. In particolare è bene
seguire alcuni accorgimenti nel tracciarle:
 Ogni colonna deve avere un’intestazione con il nome e l’unità di misura della grandezza
rilevata
4
 Tabelle troppo lunghe diventano illeggibili; meglio, quindi, riportare tabelle corte nel corpo
della relazione (dieci-venti righe al massimo), eventualmente selezionando solo alcune righe
da set completi di dati che saranno poi riportati in appendice;
 Se una tabella deve essere divisa tra pagine differenti (ma per quanto possibile è meglio
evitarlo) è necessario riportare nuovamente l’intestazione all’inizio della nuova pagina1;
 I numeri vanno allineati a destra e si deve usare la virgola come separatore decimale e non il
punto.
I grafici devono essere chiari e leggibili e riportare, in particolare la corretta unità di misura
sugli assi.
Nelle relazioni tecniche spesso sono presenti numerose equazioni, che per poter essere
agevolmente interpretate, devono essere leggibili anche dal punto di vista grafico. È chiaro, per
esempio, che la seguente formula
|W(jω)|=(Ao*s^2/ωo^2)/(s^2/ωo^2+2*ζ*s/ωo+1)
diventa molto più facile da leggere se riscritta con un editor di equazioni:
𝑠2
𝜔02
|𝑊(𝑗𝜔)| = 2
𝑠
𝑠
2 + 2𝜁 𝜔 + 1
𝜔0
0
𝐴0
Alcune osservazioni sulle equazioni:

i risultati finali dei calcoli vanno sempre corredati della corretta unità di misura;

è sempre meglio inserire le formule in righe separate rispetto al corpo del testo
distanziandole leggermente dalle righe precedente e seguente;

le equazioni, per comodità, possono essere numerate, in modo da rendere più facile riferirsi
ad esse in altri punti del testo.
1.8 La bibliografia
Poiché il lavoro di un buon tecnico si basa per il 90% sul lavoro svolto da altri prima di lui, è
indispensabile indicare in bibliografia le fonti che si sono utilizzate per la stesura del documento o
per la realizzazione del progetto. Fonti tipiche sono libri di testo, manuali, datasheet, siti internet.
La bibliografia è una parte essenziale della relazione, tanto che alcuni documenti scientifici
rivestono importanza proprio per l’ampiezza e la completezza della bibliografia in essi riportata.
Ciascuna citazione deve essere tale da permettere al lettore di risalire alla fonte
corrispondente. Nel caso tipico dei libri su supporto cartaceo la corrispondente voce in bibliografia
può presentarsi come segue:
Bobbio G., E. Cuniberti, L. De Lucchi, D. Galluzzo, S. Sammarco, E&E Elettrotecnica e Elettronica
- vol. 1, 2012, ed. Petrini
Possiamo notare come debbano essere indicati, in sequenza: autori (cognome per esteso e
iniziale del nome), titolo (ed eventualmente volume), anno di pubblicazione dell’edizione in
esame, editore. È opportuno che il titolo dell’opera sia evidenziato in qualche maniera;
1
I word processor offrono generalmente questa possibilità; è sufficiente selezionare l’opzione corretta tra le
proprietà della tabella.
5
nell’esempio sopra riportato il titolo dell’opera è stato sottolineato, ma è anche possibile
compiere scelte differenti, come per esempio usare il corsivo.
Nel presente lavoro la bibliografia è impostata in modo leggermente diverso, conformemente
ad una prassi altrettanto consolidata: il nome dell’autore è seguito dall’anno della pubblicazione,
indicato tra parentesi tonde. Il testo precedente, per esempio, verrebbe riportato così in
bibliografia:
Bobbio G., E. Cuniberti, L. De Lucchi, D. Galluzzo, S. Sammarco (2012), E&E Elettrotecnica e
Elettronica - vol. 1, ed. Petrini
e citato, all’interno del testo, in questo modo: “Bobbio et. al. (2012)”. La dicitura “et. al.” È
l’abbreviazione del latino et alii, che significa “ed altri”, ed è usato per evitare di citare tutti gli
autori di un testo appesantendo inutilmente la lettura. Se lo stesso autore ha pubblicato più testi
nello stesso anno si indicano i testi in sequenza con (2012a), (2012b) e così via.
In alternativa è possibile fare riferimento alle fonti semplicemente indicandone il numero
progressivo, riportato in bibliografia prima di ciascuna fonte; per esempio:
[1] Bobbio G., E. Cuniberti, L. De Lucchi, D. Galluzzo, S. Sammarco, E&E Elettrotecnica e
Elettronica - vol. 1, 2012, ed. Petrini
[2] Bobbio G., E. Cuniberti, L. De Lucchi, D. Galluzzo, S. Sammarco, E&E Elettrotecnica e
Elettronica - vol. 2, 2012, ed. Petrini
In questo caso, all’interno del testo, il riferimento al primo dei due libri sopra indicati sarà fatto
semplicemnete scrivendo [1].
2. Consigli per la composizione
Qui di seguito sono forniti alcuni utili consigli da utilizzare in fase di composizione della
relazione:
 Può essere utile iniziare la stesura relazione inserendo come prima cosa tutti i titoli delle
varie sezioni, così da avere fin da principio un’idea della sua struttura generale. Ciò
permette, fra l’altro, di compilare fin da subito l’indice del documento.
 Una delle caratteristiche più apprezzate di un documento tecnico è la sinteticità: relazioni
inutilmente verbose sono solamente un perdita di tempo per chi le legge! Naturalmente la
sintesi non deve andare a discapito della chiarezza. È fra l’altro utile evitare frasi lunghe e
periodi complessi, che richiedono notevoli abilità di scrittura per non confondere il lettore.
 La scelta tra forma impersonale e prima persona singolare (o plurale) è fonte di dibattiti.
Probabilmente la scelta va effettuata di volta in volta anche se, probabilmente, la forma
impersonale può rivelarsi efficace in un maggior numero di situazioni.
 Evitare di usare tempi passati o futuri, preferendo ad essi il presente. Per esempio è meglio
scrivere “Da tali prove risulta che i migliori risultati si ottengono ponendo…” piuttosto che
“Da tali prove è risultato che i migliori risultati si ottenevano ponendo…”. Ed ancora, meglio
“Se l’intensità del segnale ricevuto supera il valore di soglia, il neurone recettore si attiva a
sua volta…” invece di “Se l’intensità del segnale ricevuto supera il valore di soglia, il neurone
recettore si attiverà a sua volta…” (esempi tratti da Righini, 1999).
 Nel corso della stesura e alla fine del lavoro è d’obbligo correggere tutti gli errori ortografici
e sintattici, se non altro per rispetto nei confronti del lettore.
6
 Per riferirsi ad una determinata cosa è d’obbligo usare sempre lo stesso nome. Per esempio,
riferendosi al medesimo resistore, è vietato chiamarlo una volta RA ed una volta R1.
3. Osservazioni sull’impaginazione
L’impaginazione di un lavoro è il suo biglietto da visita. Certamente una buona impaginazione
non rende automaticamente buono un lavoro, ma rende il lettore più ben disposto alla lettura. La
cura all’aspetto grafico, inoltre, rende più facile la lettura stessa e dà l’impressione che il lavoro
che la relazione veicola sia di maggiore valore.
La diffusione dei personal computer ha reso tale lavoro molto più semplice, a patto di sapersi
destreggiare con alcune fra le principali funzionalità dei word processor. In particolare è
importante porre l’attenzione su alcuni aspetti principali:
 Scelta dei caratteri. I caratteri scelti devono essere leggibili e non devono distrarre la lettura;
fra i più usati si trovano Calibri (usata in questo documento), Arial, Times New Roman
(piuttosto inflazionato). La loro dimensione varia tipicamente tra undici e dodici punti;
ovviamente diviene maggiore per i titoli dei capitoli e dei paragrafi. In ogni caso è bene
evitare di usare una molteplicità di caratteri differenti; meglio, quindi, un unico carattere per
l’intero corpo del testo ed, eventualmente, un carattere diverso per il titolo e per alcune
parti “speciali” all’interno del testo, uqali, per esempio, i tratti di codice di programmazione.
Per il codice, in effetti, è opportuno scegliere un font nel quale i caratteri abbiano tutti la
medesima larghezza (si parla di caratteri a spaziatura fissa), ad esempio Courier New oppure
Consolas.
Tra le varie righe è bene evitare di inserire degli interlinea che, spesso, danno solamente la
sensazione di voler allungare il documento. È invece opportuno inserire una leggera
spaziatura prima e dopo ciascuna formula, al fine di renderne più facile la lettura.
 Uso degli stili. Normalmente i word processor danno la possibilità di impostare alcuni stili
predefiniti; per esempio “Titolo 1”, “Titolo 2”, “Testo normale”, ecc. Questo permette di
rendere il documento uniforme, evitando che i titoli dei paragrafi, per esempio, siano scritti
con caratteri diversi in punti differenti del testo. La loro definizione aiuta, fra l’altro, nella
numerazione di capitoli e paragrafi e nella compilazione dell’indice.
 Numerazione di capitoli e paragrafi. La lettura viene resa più agevole anche numerando la
diverse sezioni del documento. Per esempio è possibile trovare i capitoli 1, 2 e 3 e poi i
paragrafi 1.1, 1.2, 1.3 e così via; talvolta alcuni paragrafi possono contenere dei
sottoparagrafi: 1.2.1, 1.2.2, ecc. In Tabella 1 si trova un esempio di strutturazione di un
documento tecnico-scientifico.
Tabella 1. Esempio di struttura di un documento tecnico-scientifico
Titolo della sezione
Livello gerarchico
Sommario
Capitolo
Indice
Capitolo
1. Cos’è un protocollo di comunicazione?
Capitolo
2
2. Caratteristiche generali del protocollo I C
Capitolo
3. Caratteristiche fisiche
Capitolo
4. Sequenza di trasferimento dati
Capitolo
4.1 Bit di start e bit di stop
Paragrafo
7
4.2 Invio e ricezione di un bit
Paragrafo
…
2
5. Il protocollo I C con Arduino
Capitolo
5.1 Il master chiede due byte ad uno slave
Paragrafo
…
Esercizi
Capitolo
Appendice A – Osservazioni sulla capacità di un bus
Capitolo
Appendice B – Adattatori di livello
Capitolo
B.1 Adattore a MOS discreti
Paragrafo
B.2 Adattatore integrato
Paragrafo
Bibliografia








Capitolo
Per facilitare il processo di numerazione è sufficiente impostare correttamente gli “Stili”
all’interno del documento. In questo lavoro, per esempio, i titoli dei capitoli sono stati
impostati come “Titolo 1” e quelli dei paragrafi come “Titolo 2”. Avendo poi seguito la
corretta procedura è stato possibile associare a ciascuna riga con lo stile “Titolo 1” un
numero progressivo (nel caso specifico da uno a tre) e a ciascuna riga con lo stile “Titolo 2” il
numero del capitolo seguito dal numero del paragrafo (per esempio 1.3 oppure 1.4). Tale
numerazione viene attribuita in modo automatico una volta che si sia proceduto
correttamente alla definizione degli stili.
Automatizzare la compilazione dell’indice. La definizione degli stili permette anche di
automatizzare la compilazione dell’indice. È sufficiente indicare al word processor a quali stili
fare riferimento nella compilazionme dell’indice. In questo documento, per esempio, è stata
impostata la compilazione dell’indice indicando gli stili “Titolo 1” e “Titolo 2”. La
compilazione automatica consente un notevole risparmio di tempo, soprattutto quando un
indice debba essere aggiornato perché il documento è stato modificato.
Automatizzare la generazione di discalie, note a piè di pagina… Un’altra importante
funzionalità che mettono a disposizioni i moderni word processor riguarda la generazione
delle didascalie delle figure e delle tabelle e delle note a piè di pagina. Anche qui il
programma di videoscrittura permette di numerarle automaticamente in modo progressivo
evitando lo spiacevole inconveniente di dover rinumerare tutte le figure di un documento
qualora, per esempio, se ne inserisca una nuova al suo principio.
Riferimenti incrociati. Ecco due esempi di riferimenti incrociati: paragrafo 1.3 e Figura 2.
Anche la generazione di tali riferimenti può essere automatizzata. Qualora, per esempio
fosse inserita una ulteriore figura prima della Figura 2, il riferimento precedente verrebbe
cambiato automaticamente, senza la necessità che l’operatore vada a modificare
manualmente la dicitura “Figura 2” in tutti i posti in cui essa compare.
Un’impaginazione ben fatta richiede un piccolo rientro della riga all’inizio di ogni capoverso
Per rendere più semplice la ricerca di un determinato capitolo o paragrafo all’interno del
documento è opportuno inserire sempre la numerazione delle pagine
L’inserimento di pagine bianche va sempre evitato, soprattutto in documenti brevi.
Usare le funzioni “pedice” ed “apice”
Per rendere il lavoro graficamente più piacevole è preferibile giustificare il testo piuttosto
che allinearlo a sinistra.
8
Bibliografia
Bobbio G., E. Cuniberti, L. De Lucchi, D. Galluzzo, S. Sammarco (2012), E&E Elettrotecnica e
Elettronica - vol. 1, ed. Petrini
Righini G. (1999), Piccola guida alla stesura di una relazione scientifica, guida ad uso didattico
Facoltà di agraria, …
Beccari C., F. Canavero, U. Rossetti, P. Valabrega (2011), Saper comunicare – Cenni di scrittura
tecnico-scientifica, Politecnico di Torino
9