SCUOLA DI LABVIEW

11

Training per principianti

IMPLEMENTAZIONE DELLA

DOCUMENTAZIONE

E importante fornire una documentazione significativa per

supportare gli utenti del VI ed altri sviluppatori che potrebbero ereditare il VI. In questa lezione apprenderete concetti che vi permetteranno di creare standard di documentazione per il vostro lavoro.

ARGOMENTI
A. Progettazione della documentazione
B. Sviluppo della documentazione utente
C. Descrizione di VI, controlli e indicatori
D. Creare file di help
A. Progettazione della documentazione
Gli obiettivi di qualit del progetto determinano il formato e
il livello di dettaglio della documentazione che sviluppate per
requisiti, specifiche e altra documentazione relativa al progetto stesso. Se il progetto deve soddisfare uno standard di
qualit come lISO 9000, il formato e il livello di dettaglio
della documentazione sono differenti dal formato e dal livello di dettaglio di un progetto interno.
LabVIEW include caratteristiche che semplificano il processo
di creazione della documentazione per i VI che progettate.
History window - Usate questa finestra per registrare le
modifiche apportate a un VI mano a mano che le effettuate.
Print dialog box - Usate questa area di dialogo per
creare stampe del pannello frontale, del diagramma a blocchi, del pannello connettori e della descrizione di un VI.
Potete utilizzarla anche per stampare i nomi e le descrizioni di controlli e indicatori del VI e i nomi e i percorsi di
eventuali subVI. Potete stampare queste informazioni,
generare file di testo o generare file HTML o RTF che potete usare per creare file di help compilati.
B. Sviluppo della documentazione utente
Organizzare la documentazione sistematicamente aiuta gli
utenti ad apprendere il prodotto, il VI o lapplicazione.
Utenti diversi hanno esigenze di documentazione differenti. Gli utenti finali dei VI appartengono a due classi: gli
utenti finali di VI di interfaccia e gli utenti finali di subVI.
Ciascuno di questi utenti ha esigenze di documentazione
differenti.
Questo paragrafo descrive tecniche per creare e organizza-

re documentazione che aiuti entrambe queste classi di

utenti. Il formato della documentazione utente dipende dal
tipo di prodotto che create.
Organizzazione sistematica della documentazione
Per rendere la documentazione pi utile per lutente, considerate lorganizzazione della documentazione in modo
sistematico. Dividete la documentazione in tre categorie:
concetti, procedure e materiale di riferimento. Create documentazione che rifletta queste tre categorie.
Documentare una libreria di VI
Se il software che state creando una libreria di VI utilizzata da altri sviluppatori, come driver per strumentazione o
pacchetti add-on, create documenti con un formato simile
a quello del LabVIEW Help. Poich laudience costituita
da altri sviluppatori, potete ipotizzare che laudience abbia
una conoscenza operativa di LabVIEW. Create documentazione che contenga una visione dinsieme del contenuto
del pacchetto, esempi di come utilizzare i subVI e una
descrizione dettagliata di ciascun subVI.
Per ogni subVI, includete informazioni come il nome e la
descrizione del VI, unimmagine del pannello dei connettori e unimmagine della descrizione del tipo di dato per ogni
controllo e indicatore presente sul pannello dei connettori.
Per generare la maggior parte della documentazione per VI
e controlli, selezionate FileVI Properties e selezionate
Documentation dal men a tendina Category.
Selezionate FilePrint per stampare la documentazione
del VI, in un formato quasi identico al formato usato nel VI,
e informazioni di riferimento delle funzioni nel LabVIEW
Help. Usate larea di dialogo Print per salvare la documentazione in un file e per creare documentazione per pi
VI con una sola operazione.
Documentare unapplicazione
Se state sviluppando unapplicazione per utenti che non
hanno familiarit con LabVIEW, la documentazione richiede pi materiale introduttivo. Create un documento che
fornisca i requisiti di sistema, istruzioni base di installazione e una visione dinsieme del funzionamento del pacchetto. Se il pacchetto usa I/O, includete i requisiti hardware e
tutte le eventuali istruzioni di configurazione che lutente
deve completare prima di utilizzare lapplicazione.
Per ogni pannello frontale con cui lutente interagisce, for-

a cura di Matteo Foini

Questa lezione descrive tecniche per implementare la

documentazione del VI

23

SCUOLA DI LABVIEW

11

nite unimmagine del pannello frontale e una descrizione

dei principali controlli e indicatori. Organizzate le descrizioni dei pannelli frontali dallalto verso il basso, documentando per primo il pannello frontale che lutente vede per
primo. Potete anche usare larea di dialogo Print per creare questa documentazione.
Documentare un modello di progettazione
Quando implementate unarchitettura scalabile, dovreste
sempre considerare quali problemi di scalabilit potrebbero manifestarsi. Dopo avere implementato unarchitettura
per unapplicazione, difficile cambiare larchitettura di
base. Scegliete buone tecniche di programmazione per
implementare unarchitettura scalabile, perch inevitabile che voi o un altro sviluppatore avrete la necessit di
cambiare o modificare il VI in futuro. Le applicazioni e i loro
usi evolvono. Per essere certi che larchitettura che avete
scelto non richieda di essere completamente riarchitettata
o riscritta quando farete dei cambiamenti, create unopportuna documentazione sulla funzionalit dellarchitettura stessa.
Mettete uno schema o una descrizione dellarchitettura
scelta sullo schema a blocchi per illustrare la sua funzionalit e aumentare la leggibilit del modello di progettazione.
Per esempio, per migliorare la leggibilit di un VI progettato come macchina a stati, incorporate allinterno del diagramma a blocchi unimmagine del grafo della relativa
macchina a stati, come illustrato nella figura 1.

sviluppo di un VI, includendo i numeri di revisione.

Quando apportate cambiamenti al VI, registrateli e seguiteli nella finestra History. Selezionate EditVI Revision
History per visualizzare la finestra History. Potete anche
stampare la storia delle revisioni o salvarla in un file
HTML, RTF o di testo.
Numeri di revisione
Il numero di revisione un modo semplice per tenere
traccia delle modifiche apportate a un VI. Il numero di
revisione parte da zero e aumenta ogni volta che salvate
il VI. Per visualizzare il numero di revisione corrente nella
barra del titolo del VI e nella barra del titolo della finestra
History, selezionate ToolsOptions, selezionate
Revision History dallelenco Category e mettere un
segno di spunta nella casella Show revision number in
titlebar.
Il numero visualizzato da LabVIEW nella finestra History
il numero di revisione successivo, pari al numero di revisione corrente pi uno. Quando aggiungete un commento alla storia, lintestazione del commento include il prossimo numero di revisione. Il numero di revisione non
incrementa quando salvate un VI dopo averne salvato
solo la storia.
I numeri di revisione sono indipendenti dai commenti
nella finestra History. I gap nei numeri di revisione fra i
commenti indicano che avete salvato il VI senza un commento.

Figura 1 Incorporare un diagramma a stati nello schema a blocchi

Anche commentare il modello di progettazione estremamente importante. I commenti dovrebbero sempre

indicare il motivo per cui avete scelto un particolare
modello di progettazione.
Documentare la storia dello sviluppo
Usate la finestra History per visualizzare la storia dello

24

Poich la storia strettamente un tool di sviluppo,

LabVIEW rimuove automaticamente la storia quando
rimuovete lo schema a blocchi di un VI. La finestra
History non disponibile nella versione run-time di un
VI. La pagina General dellarea di dialogo delle VI
Properties visualizza il numero di revisione anche per i VI

documentazione del VI che generate.

A meno che ogni oggetto abbia una descrizione, lutente
che osserva un nuovo VI non ha altre possibilit che quella di indovinare la funzione di ogni controllo e indicatore.
Ricordate quindi di inserire una descrizione quando create loggetto. Se copiate loggetto in un altro VI, ne copiate anche la descrizione.
Ogni controllo e indicatore richiede una descrizione che
include le seguenti informazioni:
Funzionalit
Tipo di dato
Range valido (per gli input)
Valore di default (per gli input) Potete anche elencare il valore di default fra parentesi come parte del nome
del controllo o indicatore.
Comportamento per valori speciali (0, array vuoto, stringa vuota, ecc.)
Informazioni addizionali, per esempio se lutente deve
impostare questo valore sempre, spesso o raramente
Designate quali ingressi e uscite sono richiesti, raccomandati e opzionali per evitare che gli utenti dimentichino di cablare i collegamenti di subVI. Per indicare gli
ingressi e uscite richiesti, raccomandati e opzionali, cliccate con il tasto destro sul quadro connettori, selezionate This Connection Is dal men abbreviato e selezionate Required, Recommended o Optional.
D. Creazione di file di help
Se avete i corretti tool di sviluppo, create documenti di
help o di riferimento online.
Usate larea di dialogo Print per facilitare la creazione
del materiale sorgente per i documenti di help.
Dopo avere creato i documenti sorgente, usate un compilatore di help per creare il documento di help. Se vi occorrono file di help su pi piattaforme, usate un compilatore
di help per la specifica piattaforma per la quale volete
generare i file di help.
Potete anche linkarvi ai file di help direttamente da un VI.
Linkate i VI al menu Help usando la pagina
Documentation dellarea di dialogo VI Properties.
Potete anche usare le funzioni Help per linkarvi agli argomenti in specifici file di help programmaticamente.

Note sull'autore
Laureato in ingegneria nucleare al Politecnico di Milano, Matteo Foini
lavora in qualit di Technical Marketing Engineer presso National
Instruments Italy

Readerser vice.it n. 1125

senza schemi a blocchi. Cliccate il pulsante Reset nella

finestra History per cancellare la storia delle revisioni e
resettare a zero il numero di revisione.
C. Descrizione di VI, controlli e indicatori
Integrate le informazioni per lutente in ogni VI che create usando la funzionalit VI description, mettendo istruzioni sul pannello frontale e includendo descrizioni per
ogni controllo e indicatore.
Creazione di descrizioni dei VI
Create ed editate VI description selezionando FileVI
Properties e selezionando Documentation dal men a
tendina Category.
La VI description spesso la sola sorgente di informazioni su un VI disponibile allutente. La VI description appare nella finestra Context Help quando spostate il cursore sopra licona del VI e in ogni documentazione del VI
che generate.
Includete i seguenti elementi nella VI description:
Una visione dinsieme del VI
Istruzioni per luso del VI
Descrizione di ingressi e uscite
Documentare pannelli frontali
Un modo per fornire istruzioni importanti mettere un
blocco di testo ben evidenziato sul pannello frontale. Un
elenco dei passi importanti molto utile. Includete istruzioni come Selezionare FileVI Properties per istruzioni
o Selezionare HelpShow Context Help. Per istruzioni
lunghe, usate un controllo stringa scorrevole invece di
unetichetta libera. Quando finite di inserire il testo, cliccate con il tasto destro il controllo e selezionate Data
OperationsMake Current Value Default dal men
abbreviato per salvare il testo.
Se un blocco di testo richiede troppo spazio sul pannello
frontale, usate invece un pulsante Help sul pannello frontale. Includete la stringa di istruzioni nella finestra di help
che appare quando lutente clicca il pulsante Help. Usate
la pagina Window Appearance nellarea di dialogo VI
Properties per configurare questa finestra di help come
unarea di dialogo che richiede che lutente clicchi un pulsante OK per chiuderla e continuare, o come una finestra
che lutente pu spostare ovunque e chiudere in qualsiasi momento.
Potete anche utilizzare un pulsante Help per aprire una
voce in un file di help online. Usate le funzioni Help per
aprire la finestra Context Help o per aprire un file di
help e accedere a un argomento specifico.
Creare descrizioni di controlli e indicatori
Includete una descrizione per ogni controllo e indicatore.
Per creare, editare e visualizzare le descrizioni degli
oggetti, cliccate con il tasto destro loggetto e selezionate Description and Tip dal men abbreviato. La descrizione delloggetto appare nella finestra Context Help
quando spostate il cursore sopra loggetto e in ogni

25