tratto da technische kommunikation | Volume 31 | 1 / 2009
traduzione di Lia D'Antonio

Uso di Help & Manual versione 5

Fino a pochissimo tempo fa, lo strumento di authoring Help & Manual era più noto tra gli sviluppatori software che tra i technical writer. Tuttavia, con la nuova versione 5, Help & Manual è diventato una seria alternativa ai famosi leader di mercato nel campo degli strumenti di authoring per lo sviluppo di sistemi di guida, quali RoboHelp o Flare. La chiave del successo di Help & Manual è la sua unica efficienza: ad oggi, infatti, non esiste un altro sistema di authoring che permette di conseguire risultati di livello professionale con altrettanta rapidità.

Help & Manual molto chiaramente è destinato alla creazione di documentazione software. Come suggerito dal nome stesso, infatti, è possibile utilizzarlo per produrre, da una comune sorgente testuale, ossia la "sorgente unica" (single source), la guida in linea in tutti i formati attualmente in uso nonché manuali cartacei. Help & Manual si distingue da quasi tutti gli altri sistemi concorrenti in quanto crea direttamente i file PDF, senza passare per convertitori esterni o programmi di layout quali Microsoft Word o Adobe FrameMaker.

Analogamente alla maggior parte degli altri strumenti comparabili, presenta un comodo Editor WYSIWYG. Nella versione Professional è anche possibile editare direttamente il codice XML sottostante. Il software non pone alcun requisito straordinario al sistema ed è molto stabile.

Testi condizionali

Il testo o le immagini che non devono comparire in tutti i supporti e le varianti di output sono compresi nella visualizzazione in modalità WYSIWYG in istruzioni "IF … THEN ... ELSE" di colore rosso, come mostrato nella Figura 1. Inoltre, è possibile escludere interi argomenti da specifiche versioni.

 

Fig. 1: schermata utente (GUI) e testi condizionali

Un problema caratteristico della pubblicazione da sorgente unica consiste nel verificare ciò che accade ai collegamenti ipertestuali durante l'output alla stampante:

• Se i collegamenti appaiono in una sezione separata, ad esempio in un titolo interposto "vedere anche", è possibile selezionare questa intera sezione come blocco di testo condizionale. In questo caso, non figurerà nel manuale. Se un collegamento è incorporato all'interno di una frase, Help & Manual adotta un approccio pratico e inserisce una piccola icona a forma di pagina dopo il riferimento incrociato del manuale, fornendo il numero di pagina in questione, come illustrato nella Figura 2. Ciò però non è possibile con formulazioni del tipo "vedere pagina xy". Di primo acchito, per quanto occorra prendervi dimestichezza, questo metodo senza dubbio consente all'autore un notevole risparmio di tempo e semplifica la manutenzione. Non comporta particolari "acrobazie" in fase redazionale, è caratterizzato da una lingua neutra e pertanto non pone problemi in caso di traduzione.

Fig. 2: applicazione di riferimenti incrociati (collegamenti) nell'output di stampa

Riutilizzo del contenuto

Un buon sistema di single source publishing è tale se i contenuti già creati possono essere impiegati più volte, in diversi punti e in vari documenti. A partire dalla versione 5, Help & Manual offre tutti i meccanismi normalmente utilizzati a tal fine:

• ricorrendo a variabili di testo, è possibile inserire, con la frequenza che si desidera, porzioni di testo quali il nome di un prodotto o il numero di versione. Cambiando una variabile di testo, tale modifica si rifletterà automaticamente in tutti i punti del testo in cui compare la stessa variante.
• È possibile salvare sezioni più ampie, formate da uno o più paragrafi sotto forma di frammenti basati su XML , che, contrariamente alle variabili di testo, contengono tutta la formattazione del tipo di paragrafo e carattere e, oltre al testo, possono anche includere immagini e dati multimediali. Se si inserisce un frammento in un argomento, è possibile scegliere se questa istanza deve essere sincronizzata con il frammento, vale a dire, se deve essere modificata automaticamente o meno al variare dei frammenti.
• È possibile usare tante volte di seguito interi argomenti, in maniera analoga, attraverso il meccanismo dei frammenti, in documenti diversi o lavorare con "progetti uniti", in cui parti di un progetto sono collegati in modo dinamico a un altro progetto.

Produzione della guida in linea

Per progettare la guida in linea, è possibile utilizzare interfacce già pronte o persino personalizzare il layout e il codice HTML sottostante (vedere Figura 3). Inoltre, il produttore offre anche un "Premium Pack" con più interfacce, sempre modificabili individualmente. Questa funzione è espressamente prevista nelle condizioni della licenza del Premium Pack. La dotazione d'uso comprende anche i file di codice sorgente e immagine nel formato Photoshop.
All'occorrenza, è possibile inserire anche un codice HTML o JavaScript a scelta all'interno degli argomenti, il che consente anche di apportare modifiche straordinarie.

Fig. 3: enorme libertà di personalizzazione dei codici HTML sottostanti

Nella versione Professional, l'applicativo supporta moderni strumenti di navigazione quali i Breadcrumb e sezioni espandibili, nonché miniature per la grafica.
Quando si avvia il processo di produzione, è possibile selezionare il supporto da creare in una data versione. Nella Figura 4, ad esempio, è raffigurata una guida in formato HTML del browser ("guida web") per la variante B del prodotto ("VERSION_B").

Fig. 4: scelta delle varianti da generare

Il programma crea una guida complessa nei formati CHM, Visual Studio Help (MS Help 2.0) e di guida, così come semplici guide basate su browser ("guida web"). Inoltre serve anche a realizzare eBook eseguibili tanto come file EXE o nel formato EPUB.

È importante notare che la guida del browser può essere richiamata facilmente in modo sensibile al contesto da un programma o un'applicazione web; il sommario viene sincronizzato automaticamente. Le guide del browser sono stabili per quanto riguarda tutti i browser in uso e presentano una ricerca di testo globale molto veloce. Questa funzionalità però è fruibile solo se la guida è stata creata con la versione Professional e non semplicemente con quella Standard.

Produzione di manuali cartacei

Nell'impostazione predefinita, i formati del paragrafo e del carattere per la versione di stampa in PDF corispondono all'output in linea. Tuttavia, è possibile definire delle proprietà completamente diverse per ogni formato.

Il layout della pagina e il layout di tutti gli elementi per i quali non esiste una corrispondente versione in linea, quali la pagina del titolo o la sezione del marchio, verranno salvati in uno speciale modello di stampa, il quale viene creato mediante un tool separato, il "Print Manual Designer". La fornitura comprende una serie di modelli già pronti. Ma, ad eccezione dei layout con svariate colonne, è possibile implementare quasi tutte le singole idee di layout.

Il Print Manual Designer, che è simile nella struttura a un programma di disegno, presenta una scheda separata per ogni tipo di pagina, quale il frontespizio, il sommario, le pagine di inizio capitolo e la pagina dell'indice. Da queste schede è possibile eseguire tutte le impostazioni della pagina e salvare gli elementi costanti quali immagini di sfondo e intestazioni e piè di pagina.

Fig. 5: il Print Manual Designer è un applicativo per la creazione dei manuali.

Nel modello sono presenti segnaposto per tutti i contenuti che verranno inseriti in maniera dinamica solo al momento della produzione dall'origine dati centrale, quali le voci di sommario e tutti i testi di singoli capitoli e sezioni.

La produzione dei manuali viene realizzata in maniera del tutto automatizzata. Un aspetto particolarmente gradito in questo caso è la possibilità di fare a meno di qualsiasi tipo di aiuto o strumento esterno e del "post-processing" esterno in qualsiasi fase. Help & Manual crea una file PDF pronto sulla base del layout salvato in piena autonomia. Non saranno necessari Adobe Acrobat, i relativi driver speciali della stampante, i processi XML o qualsiasi programma di layout esterno quale Word o FrameMaker.

Un manuale che si articola in un centinaio di pagine sarà 'confezionato' in pochi minuti ed è in grado di soddisfare i requisiti più severi sotto il profilo dell'aspetto e dell'appeal visivo. Il sommario, l'indice e il riferimento incrociato hanno tutti collegamenti ipertestuali cliccabili.

La produzione può essere avviata manualmente, dall'Editor, o direttamente dalla riga di comando. In questo modo, con un semplice file batch, è possibile generare automaticamente tutti i documenti in un'unica fase di lavoro: tutte le guide in linea per tutte le varianti del prodotto e tutti i manuali di tutte le varianti stesse con le rispettive interfacce e modelli su cui si basano. Anche le variabili di testo possono essere impostate in modo dinamico dalla riga di comando.

Punti di forza

I punti di forza di Help & Manual in particolare sono il setup semplice e l'efficacia del flusso di lavoro. Non occorre utilizzare componenti esterni, quali banche dati, convertitori o layout engine. In questo modo si semplifica in misura notevole la configurazione e la manutenzione, si riduce la suscettibilità agli errori e si agevola enormemente l'utilizzo.

I componenti delle informazioni possono essere contrassegnati a tutti i livelli di granularità come testi condizionali o persino riutilizzati in più punti.
Help & Manual è compatibile con UNICODE e supporta i processi di traduzione basati su XML. I progetti possono essere inviati ai traduttori come dati XML con un semplice clic di un pulsante e importati in maniera analoga.

La versione Professional supporta anche il lavoro di squadra e, in futuro, supporterà il collegamento a una gestione delle versioni con SCC-API. Ciò consentirà di utilizzare Help & Manual con la maggior parte degli strumenti di gestione delle versioni.

Help & Manual è estremamente stabile nel funzionamento giornaliero. Il programma si blocca molto raramente. I dati editati non vengono compromessi in caso di arresto anomalo del sistema dovuto a fattori esterni. Anche i documenti creati, in particolare la guida del browser, funziona in maniera stabile in varie configurazioni del sistema e in vari sistemi operativi.

La fornitura comprende uno strumento completo di acquisizione dello schermo e un programma professionale di editing delle immagini. Anche i testi tratti dalle immagini possono essere esportati in XML ai fini della traduzione, per poi essere reimportati nelle immagini stesse.
La documentazione, pur se disponibile solo in lingua inglese, è molto dettagliata e di buon livello.

Punti di debolezza

La versione di stampa (PDF) non supporta la sillabazione o i layout con più colonne. Non supporta le annotazioni a margine. In particolare, in presenza di tabelle e testi condizionali, ciò potrebbe generare interruzioni di pagina e pagine vuote inattese, che possono essere ovviate solo con espedienti implementati manualmente. Persino il posizionamento della pagina stampata non è sempre accurato a un decimo di millimetro. Nonostante i processi di produzione automatizzati, il software in linea generale offre risultati molto interessanti. Tuttavia, a lungo andare chiunque desideri ottimizzare ogni interruzione di linea o di pagina individualmente potrebbe non essere soddisfatto di Help & Manual.

Nell'impostazione predefinita, l'interfaccia utente, basata sull'interfaccia Ribbon di Microsoft Office, occupa un'ampia parte dello schermo. La vera e propria finestra dell'editor per l'acquisizione dei testi potrebbe essere ridotta enormemente in presenza di monitor a bassa risoluzione. In questo caso, potrebbe risultare utile disattivare il "Ribbon" e popolare manualmente "la barra degli strumenti di accesso rapido" con le funzioni usate più di frequente.
Il controllo ortografico tedesco non è in grado di riconoscere un numero alquanto elevato di parole e, inizialmente, deve essere "istruito" dall'utente.

Le sezioni espandibili ("attivazioni/disattivazioni") e le miniature cliccabili delle immagini ("attivazioni/disattivazioni screenshot") possono essere create solo con la versione Professional, analogamente alla ricerca di testo globale per la guida basata sul browser.

Per quanto sia completamente basato su XML, Help & Manual è in grado di comprendere solo la propria struttura XML. Non è possibile editare i dati in base a DITA, DocBook o altri DTD.

Alternative

Le alternative dirette a Help & Manual sono principalmente RoboHelp di Adobe e Flare di MapCap Software. Tuttavia, ambedue questi prodotti sono più costosi e complessi da usare. Rispetto a Help & Manual, Flare presenta maggiori opzioni per la definizione dei dettagli. Inoltre, insieme a FrameMaker, Word o Blaze, può implementare più layout di stampa fuori standard. Help & Manual non presenta alcuna gamma di prodotti supplementari, a differenza di MadCap Software che è fornito con MadCap Analyzer, MadCap Feedback e X-Edit.

Per giunta, il prodotto HelpStudio di Innovasys si basa su un approccio che è molto simile a quello di Help & Manual. In questo caso, però, la produzione dei PDF non è altrettanto flessibile come in Help & Manual; ma con la Community Extension è disponibile anche un prodotto fornito a corredo che consente di includere le classificazioni e una funzione di commento in una guida in linea basata sul web, e Dynamic Help SDK, un componente per la guida incorporata.

Sintesi

Help & Manual è un programma completo di creazione avanzata e professionale per la documentazione software, con un buon rapporto qualità-prezzo. Sono veramente pochi i programmi altrettanto convincenti in modo così completo. È possibile creare guide in linea e manuali cartacei da una sorgente unica senza un eccessivo sforzo di configurazione, e, ove richiesto, si possono realizzare anche diverse versioni.

Malgrado l'approccio modulare basato su XML, Help & Manual, tuttavia non è il classico sistema di gestione dei contenuti e, pertanto, è più adatto all'authoring di gruppi di piccole dimensioni e per progetti con un numero limitato di varianti del prodotto. Inoltre, Help & Manual non è un editor XML universale, nonostante l'uso uniforme di XML.

Il layout della guida in linea da creare può essere personalizzato a piacere per soddisfare le esigenze individuali. Nel layout di stampa, potrebbe essere necessario scendere a piccoli compromessi, ma si ridurrà sensibilmente il dispendio di tempo e denaro nel processo di creazione.
Pertanto, Help & Manual è consigliabile per tutti coloro che nel lavoro sono soggetti a pressioni in termini di costi e tempi e desiderano creare guide in linea e manuale da una sorgente unica , senza molta frustrazione o costi iniziali.

Panoramica di Help & Manual 5

Requisiti di sistema
Windows Vista, XP o 2000; RAM 512 MB; spazio disponibile sul disco fisso di 70 MB; risoluzione dello schermo di almeno 1024x768, 1280x1024 o meglio se maggiore

Prezzi
Versione Standard circa 260 Euro
Versione Professional circa 400 Euro
Premium Pack circa 60 Euro.

Informazioni
EC Software GmbH
www.helpandmanual.com

Marc Achtelig, ingegnere diplomato (scuola tecnica superiore) e ingegnere gestionale diplomato (scuola tecnica superiore) è un autore e un consulente aziendale nel campo della comunicazione tecnica. È specializzato nella documentazione software, nei sistemi di documentazione interattivi e nel single source publishing.
Contatto: ma@indoition.de