Intervista con Alessandro Stazi su MadCap Flare e altri temi della comunicazione tecnica

postato da Petra Dal Santo - KEA s.r.l. [14/08/2013 10:23]
foto

Alessandro Stazi è autore del blog L’Artigiano di Babele - Il blog del technical writer (http://www.artigianodibabele.it/) e lavora come Technical Documentation & Training Manager per l’azienda CrossIdeas di Roma (http://www.crossideas.com/CrossIdeas/). Lo abbiamo intervistato a proposito della sua esperienza di adozione del software per la gestione della documentazione tecnica MadCap Flare

In un post di metà giugno Alessandro racconta brevemente della sua esperienza di “apprendista entusiasta” di MadCap Flare (http://www.madcapsoftware.com/), software per la realizzazione di documentazione tecnica per help online, documentazione software, manuali di policy e procedure, knowledge base e guide utente.

L’idea dell’intervista nasce da qui: ci è sembrato particolarmente interessante raccogliere le osservazioni non di un “super-esperto” del software, ma di un utente che ha iniziato ad apprendere il sistema e a utilizzarlo per realizzare come primo progetto il nuovo help online della piattaforma software di CrossIdeas.

Petra Dal Santo (PDS): Quali sono i motivi principali che hanno spinto CrossIdeas ad adottare MadCap Flare?

Alessandro Stazi (AS): Avevamo da tempo la necessità di migliorare l’attività di authoring/publishing della documentazione aziendale. Con nuovi clienti e partner commerciali anche fuori dai confini nazionali, con la forte evoluzione tecnica della nostra piattaforma software, volevamo migrare verso un approccio sempre più basato su:

  • single source
  • ri-uso dei contenuti
  • documentazione principalmente web-based
  • multicanalità e multipiattaforma.

Tutto ciò si poteva ottenere solo con strumenti evoluti. In realtà, già da due anni, nei ritagli di tempo, stavo portando avanti un’attività di scouting per capire quali fossero i migliori prodotti sul mercato che consentissero di ottenere tutto ciò. Quindi, quando l’esigenza si è presentata, ero pronto. E l’esigenza ha preso la forma del nuovo Help on Line da integrare nella nostra nuova architettura.

Era necessario capovolgere radicalmente il paradigma, passare da una documentazione pensata per manuali stampabili ad una topic-oriented, in formato HTML, per realizzare l’HoL e per erogare eventuali contenuti via web.

Flare ha vinto in un set finale di 4 prodotti (tra cui anche Argo) [Nota PDS: all'epoca della software selection Argo CMS, il software di KEA, non disponeva ancora di un export in HTML (ora disponibile), per cui non rispondeva alle esigenze di CrossIdeas].

Abbiamo acquisito l’intera suite di MadCap verso la fine di Marzo.

Abbiamo avuto bisogno di circa un mese per prendere confidenza con i meccanismi principali di Flare, fare alcuni test, orientarci per capire quale potesse essere l’approccio più proficuo, commettendo qualche errore che ci è servito a correggere la rotta.

Nella prima decade di Maggio è partito il nostro primo progetto per la realizzazione del nuovo HoL.

A metà Luglio, la prima versione dell’HoL era pronta.

PDS: Hai svolto le attività di riscrittura e riorganizzazione della struttura dei contenuti prima o dopo la migrazione a MadCap Flare? Oppure hai iniziato a utilizzare MadCap Flare avviando un nuovo progetto di documentazione tecnica?

AS: Abbiamo scelto la seconda strada. All’insegna del classico “learning by doing” abbiamo via via modularizzato i contenuti, creando ex-novo quelli che dovevano documentare le nuove features e riorganizzando quelli che necessitavano solo di aggiornamenti parziali.

Abbiamo integrato circa 2000 pagine di documentazione tradizionale, correggendo in corsa alcune impostazioni e rivisitando la logica dell’esposizione dei contenuti.

Del resto, dopo poco più di 3 settimane di self-training, avevamo solo 8 settimane per l’effettiva migrazione dei contenuti e la realizzazione del nuovo HoL. Non potevamo pensare ad un approccio di ri-definizione dei contenuti fuori dai tempi del progetto, abbiamo fatto tutto in-line.

Alla fine sono state  11 settimane, un ritardo più che accettabile, considerando che era il primo progetto. Ovviamente la prima versione è assolutamente perfettibile e già per i primi di Settembre potremo fornire una nuova versione ampiamente migliorata.

PDS: Quali sono i tool di importazione con i quali MadCap Flare ha supportato il tuo popolamento primario dei contenuti? MadCap Flare dispone di funzioni particolari per l'importazione di tabelle e archivi di immagini?

AS: Flare consente d’importare contenuti di 5 tipologie principali (vd. sotto lo screenshot 1).

Il processo d’importazione è costituito da un wizard composto da diversi step e ad ogni passo si possono configurare diversi parametri. Dalle diverse combinazioni di questi parametri derivano diversi comportamenti del processo d’importazione.

Per ora abbiamo sperimentato soltanto l’importazione di documenti MS Word in formato .docx. Le immagini contenute in un file doc/docx vengono automaticamente riconosciute e salvate in una cartella che prende il nome del file doc/docx importato (del primo file della lista se viene importato più di un file); la cartella d’immagini viene poi posizionata, nella gerarchia del progetto, sotto la cartella Resource.

Anche le tabelle immerse nel file doc/dcx vengono automaticamente riconosciute e importate con lo stile tabella di default.

Non ho ancora testato l’importazione di interi archivi di sole immagini, in questa prima fase non avevamo questa necessità.

PDS: Che tipo di formazione offre MadCap Flare? On-site, on-line o in modalità self-help (documentazione, knowledge base, forum, ecc.)? Secondo la tua esperienza, quali sono i tempi di apprendimento?

AS: Uno dei motivi per cui ho scelto Flare attiene alla sua curva d’apprendimento.

Durante la fase di scouting, avevo letto i commenti di decine di esperti ed utilizzatori ed erano tutti concordi nell’indicare una certa facilità nell’acquisire confidenza con tutte le funzioni fondamentali del prodotto in poco tempo. La mia esperienza conferma questo orientamento.

In generale, MadCap mette a disposizione un Help estremamente ricco e dettagliato, un gran numero di manuali in formato PDF, video tutorial molto efficaci ed un Forum ricco di argomenti e molto attivo. Inoltre, sono disponibili numerosi webinar sugli aspetti più diversi della suite.

Se hai l’occhio minimamente allenato su queste tecnologie, puoi tranquillamente iniziare un percorso di self-training che in pochi giorni ti consentirà di confezionare il tuo primo progetto, magari usando solo le caratteristiche di base.

Ovviamente, per gestire un progetto di un certo livello, è bene studiare in profondità tutti gli aspetti avanzati del prodotto. MadCap mette a disposizione anche dei percorsi di certificazione, proprio perché è un prodotto che si presta a coprire un vasto arco di esigenze, a diversi livelli.

Ad esempio, solo per la gestione degli stili, esiste un manuale di circa 900 pagine.

Con l’uso dei fogli di stile e del meccanismi di ereditarietà delle classi di stile si possono gestire situazione molto sofisticate e questo è solo uno degli aspetti che si prestano a notevoli approfondimenti.

Ma per un primo approccio “rapido” è sufficiente sfruttare le impostazioni “di base” per “toccare con mano” il comportamento del prodotto e iniziare a prendere confidenza.

PDS: Hai incontrato difficoltà particolari nell'adozione di MadCap Flare?

AS: Francamente devo dire di no.

Sono di fatto “un’apprendista” nel mondo di Flare e molti aspetti per ora li ho avvicinati con cautela, senza sfruttare tutta la potenza espressiva di certe soluzioni. Ma le difficoltà che ho incontrato credo siano assolutamente nella norma, del tutto simili a quelle che si possono incontrare ogni volta che si “impara” un nuovo tool o una nuova tecnologia/metodologia. La documentazione disponibile copre largamente tutti gli aspetti di cui mi sono potuto occupare fino ad ora. La gestione degli stili è sicuramente uno degli aspetti più articolati e ricchi di implicazioni. 

PDS: Quali sono le caratteristiche di MadCap Flare che apprezzi maggiormente?

AS: Tra i pochi difetti che alcuni mi avevano riferito, vi era la complessità dell’interfaccia grafica. Ora che l’ho sperimentata, userei il termina “ricca” più che il termine “complessa”.

E’ un prodotto integrato nel mondo Microsoft (è imperniato sul framework .NET e usa come DB Microsoft SQL) e l’interfaccia grafica ricalca largamente quella di Word, quindi risulta essere da subito molto “familiare”. Tutte le features di base sono abbastanza “intuitive”, basta una giornata per  orientarsi senza grandi problemi.

Un altro motivo che mi ha spinto a scegliere Flare è stato l’ampio spettro di formati di output disponibili: (vd. sotto lo screenshot 2)

Il numero ed il tipo di formati varia anche in funzione del tipo di progetto che si vuole impiantare (un HoL, una KB, un e-book o altro).

PDS: MadCap Flare offre supporto allo standard DITA (Darwin Information Typing Architecture). Secondo la tua esperienza, in Italia quanto sono diffusi la conoscenza e l'utilizzo di DITA? Personalmente, prevedi di adottare questo standard in futuro?

AS: Non ho dati su cui ragionare ma per la mia esperienza credo che DITA sia veramente poco diffuso in Italia. DITA è una straordinaria metodologia di strutturazione dei contenuti, ma credo che sia particolarmente utile solo se:

  • i volumi di documentazione da produrre sono notevoli
  • la % di ripetizione dei contenuti è apprezzabilmente congrua e costante nel tempo
  • si è ragionevolmente certi che tali parametri rimangano invariati nel medio-lungo periodo (alcuni anni).

DITA richiede uno sforzo iniziale non banale; per una piccola-media impresa che desidera produrre la propria doc in casa,  la fase di start-up di un processo di authoring/publishing DITA-based è veramente impegnativo. Se invece si produce la documentazione in outsourcing, la faccenda è molto diversa.

Flare consente di produrre ouput secondo lo standard DITA e importa contenuti da progetti DITA-based, ma questa modalità non l’ho mai sperimentata.

Nella mia realtà, oggi ci troviamo a gestire un volume di contenuti che può essere stimato intorno alle 2000 pagine di documentazione “tradizionale”. Tra la fine del 2013 e tutto il 2014, prevedo che possa raddoppiare fino a raggiungere la soglia delle 4000 “pagine equivalenti”, ma anche un tale aumento non giustificherebbe l’adozione di DITA.

E’ chiaro che per un’azienda che invece deve produrre ogni anno almeno un centinaio di manuali, DITA può essere la soluzione ideale, in grado di ridurre i costi e aumentare la qualità dei contenuti.

PDS: Alessandro, molte grazie per questa intervista e buon lavoro!

***


MadCap Flare - Screenshot 1
 

 
MadCap Flare - Screenshot 2