mercoledì 28 agosto 2013

Microsoft Manual of Style for Technical Publication

Amplifico una segnalazione di Vilma Zamboli, che era intervenuta con un commento nel post relativo alla Apple Style Guide.

E' disponibile la quarta edizione del Microsoft Manual of Style for Technical Publication.

In rete è liberamente scaricabile la terza edizione.

Vilma, grazie per la "dritta"! Leggi questo articolo...

venerdì 23 agosto 2013

La mia "prima volta" con Flare: intervistato da Petra Dal Santo

In un post dello scorso Giugno vi avevo segnalato che ero molto impegnato con un "giocattolo nuovo", MadCap Flare.

Verso la metà di Luglio ha visto la luce il primo Help OnLine realizzato con Flare, per la nuova edizione della piattaforma software prodotta dall'azienda in cui lavoro. Petra Dal Santo, di cui vi ho parlato spesso negli ultimi mesi, ha voluto intervistarmi nella veste di "apprendista entusiasta" di Flare.

Potete leggere l'intervista nel suo blog.

Ho subito fatto presente a Petra che, ad oggi, non sono certamente un "super-esperto" di Flare, come del resto nessuno che abbia realizzato un solo progetto con una qualsiasi nuova tecnologia.

Ma a Petra interessava proprio il punto di vista di un "apprendista", che sta imparando ad usare una nuova tecnologia con una finalizzazione precisa, cioè un risultato che DEVE essere ottenuto in tempi molto stretti e ben definiti.

In generale, imparare una tecnologia nel "comodo" percorso didattico che si può intraprendere in un corso di formazione, per quanto ben fatto e di livello, è cosa diversa da una situazione del tipo "learning by doing", in cui mentre impari hai le scadenze del progetto che bussano alla porta del tuo ufficio e quello che impari deve tradursi, in tempo reale, in soluzioni efficaci ed effettive.

Ed era proprio questo il senso dell'intervista di Petra.

Buona lettura!



Leggi questo articolo...

martedì 20 agosto 2013

La nuova Apple Style Guide 2013: da non perdere

Vi segnalo la disponibilità della nuova guida di stile della Apple.

La potete scaricare liberamente in formato PDF.

Vi ho già parlato del ruolo e dell'importanza delle Guide di Stile. Sulla destra trovate una sezione specifica dedicata a questo argomento. A presto.


Leggi questo articolo...

lunedì 19 agosto 2013

Il nuovo sondaggio di Sharon Burton: da scaricare e da valutare

Lo scorso anno vi avevo segnalato un'indagine condotta da Sharon Burton intitolata: "Consumer Feelings About Product Documentation".

Durante il 2013 Sharon ha continuato a raccogliere dati ed ha arricchito il sondaggio con altre 3 domande (numero 14, 15 e 16) inerenti alla "qualità" della documentazione di prodotto che, in qualche modo, viene percepita dal cliente.

Dai risultati della Domanda 14 emerge chiaramente come i consumatori si aspettino un'elevata qualità della documentazione che accompagna un prodotto proporzionale al suo prezzo (52%). Ma almeno un consumatore su 3 si aspetta comunque un'elevata qualità anche indipendentemente dal prezzo del prodotto.



La Domanda 15 è indicativa delle aspettative dei consumatori rispetto al prezzo del generico prodotto. Personalmente sono molto sorpreso dal fatto che il 37% degl intervistati si aspetta di trovare della buona documentazione anche per prodotti dal prezzo bassissimo, nella fascia che va da 0 a 25$! Ma questo dato conferma quanto emerge dalla 14.



I risultati della Domanda 16 sono DEVASTANTI: pochissimi utenti sono disponibili a pagare qualcosa "di più" per ottenere una migliore documentazione. Il 66% da per scontato che una documentazione di buon livello DEVE essere inclusa nel prezzo.



Seguendo questo link, potete scaricare liberamente un PDF che contiene un estratto dell'indagine. Se volete un documento più esteso e completo, potete acquistarlo presso Amazon per poco più di 7$, nella versione per Kindle.

Fatemi avere le vostre impressioni. Leggi questo articolo...

venerdì 9 agosto 2013

Dalla scrittura monolitica alla scrittura modulare: DITA overview (dal blog di Petra Dal Santo)

Da un po' di tempo stavo preparando un lungo post per offrirvi una visione generale e completa su DITA (Darwin Information Typing Architecture), uno degli standard più importanti per la strutturazione dei contenuti tecnici.

Ma all'inizio della settimana mi sono accorto che Petra Dal Santo, sul suo blog, aveva pubblicato un ottimo articolo sull'argomento, sollevandomi dal gravoso incarico di terminare la mia fatica!

E in onore al principio del "riuso dei contenuti", vi invito a leggere il suo lavoro, molto ben realizzato.

DITA nasce nella pancia di IBM e viene poi "regalato" alla comunità "open" come standard OASIS.
IBM, fin dall'inizio degli anni '90 del secolo scorso, si trovò a dover gestire migliaia di manuali, con una rilevante percentuale di ripetizione dei contenuti. Come razionalizzare tutto il ciclo di sviluppo e produzione della manualistica, migliorando la qualità dei contenuti, abbattendo i costi e i tempi di realizzazione? La risposta fu DITA, una metodologia basata sullo standard XML che consente di realizzare contenuti ri-usabili e topic-oriented.

Vi rimando al lavoro di Petra per una panoramica di tutte le caratteristiche salienti e mi limito ad una considerazione "filosofica".

Da molti anni, anche tra coloro che apprezzano DITA, si discute sulla sua effettiva "semplicità d'uso".

Io non utilizzo DITA per produrre la documentazione tecnica di CrossIdeas, l'azienda in cui lavoro. E il motivo è semplice.

Lo sforzo iniziale che si richiede per produrre documentazione secondo le regole di DITA è molto elevato ed è giustificabile 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).
Inoltre, è altamente improbabile che siate in grado, al primo progetto, di mettere su un processo di authoring e publishing "DITA-based" se non vi affidate alla consulenza esterna di professionisti esperti, che possano fornirvi un minimo di formazione di base e vi possano aiutare ad avviare i necessari processi.

In altri termini, DITA è una straordinaria metodologia per le esigenze di IBM (che produce i suoi manuali con questo standard) e per altre grandi aziende che producono tecnologia, ma dubito che una piccola/media impresa  possa investire su DITA per produrre i suoi 15-20 manuali, che descrivono prodotti che cambiano rapidamente nel tempo.

Ma questa è solo la mia opinione. Aspetto le vostre indicazioni. Leggi questo articolo...