Dopo aver stabilito quali/quanti documenti devono accompagnare il nostro prodotto, ci troviamo davanti alla prima pagina bianca del primo manuale.
E' un evento inevitabile e il "panico da foglio bianco" è una sensazione ben nota, che tutti noi abbiamo provato almeno una volta nella vita.
Esistono diverse tecniche per esorcizzarlo e di certo sarebbe utile disporre di un "template", cioè di un modello che, fin dall'inizio, ci aiutasse a delimitare la forma e la struttura dei contenuti che dobbiamo articolare.
PERCHE' USARE UN TEMPLATE?
In primo luogo, semplicemente perchè consente di risparmiare una gran quantità di tempo che, come ben noto, è denaro.
In secondo luogo, perchè l'omogeneità stilistica è uno dei principali parametri per identificare la qualità di un documento.
Non ci credete? Provate a scaricare, dal sito istituzionale della IBM, due o tre Redbooks.
Apriteli in sequenza, uno dopo l'altro, saltellando a caso fra i contenuti. Non è necessario essere un esperto di informatica, anzi non è necessario nemmeno capire cosa state leggendo, per "avvertire" la qualità di questi documenti. La loro sobria ed efficente solidità stilistica, di per se stessa, vi trasmetterà istantaneamente la sensazione di un oggetto "ben realizzato" e questo è importante.
In tal senso, un insieme ben definito di template permette di realizzare un insieme di documenti che contribuiscono al brand della vostra azienda. Cosa c'è di peggio che inviare al cliente di turno un set di manuali con un "look and feel" non omogeneo, disordinato e privo di un stile riconoscibile come quello "proprio" dell'azienda ?
A differenza della documentazione di marketing, che deve colpire la fantasia del cliente, sollecitandolo con meccanismi anche aggressivi o sorprendenti, ben noti agli esperti di pubblicità, la documentazione tecnica deve essere "rassicurante" e facile da usare; se vi abituate ad utilizzare dei template ben strutturati, potrete raggiungere questo obiettivo più agevolmente.
Un template può contenere diversi elementi, alcuni dei quali sono elencati di seguito:
- lo stile e la struttura della copertina (front cover)
- lo stile dell'indice generale del documento
- gli stili dei paragrafi usati nel documento
- i livelli di profondità dei titoli e dei paragrafi
- il layout di ogni elemento di ogni pagina
- lo stile dell'header e del footer
- lo stile dele tabelle
- lo stile delle note
- lo stile e la struttura del glossario
- lo stile e la struttura della bibliografia
- lo stile e la struttura della quarta di copertina (back cover)
- altro ancora...
E' impensabile, per ogni documento di ogni prodotto, ridefinire ogni volta da zero tutti questi elementi che possono esser strutturati solo a valle di un gran lavoro di progettazione e design, quasi sempre attraverso raffinamenti successivi, che richedono tempo ed esperienza.
Nell'azienda in cui lavoro, ho impiegato circa 3 anni per mettere a punto, per approssimazioni progressive, un certo numero di template efficaci e ritengo di dover ancora migliorarne alcuni aspetti, senza considerare tutti i template che devo ancora mettere a punto.
Un template ben fatto può essere riutilizzabile da writers diversi, che non dovranno preoccuparsi di definire la struttura del documento ma potranno focalizzarsi solo sui contenuti.
Un template consente di ridurre gli errori.
Ad esempio, la versione di un prodotto viene di solito riportata nel titolo del manuale, nella quarta di copertina e nel footer di ogni pagina. Legando questi elementi con un "campo dinamico", sarà possibile apportare le necessarie modifiche in ogni punto del documento, semplicemente modifcando tale campo; un writer poco accorto invece, si metterebbe a modificare "a mano" questa informazione in tutti i punti del documento in cui essa compare, con un notevole dispendio di tempo e rischiando quasi certamente di non riuscire ad aggiornare correttamente tutti i riferimenti presenti.
Insomma, non c'è veramente nessun buon motivo per non usare un template.
Il tempo che inizialmente dovrete investire per costruire un buon template, lo riguadagnerete cento volte in seguito.
In futuro, nella sezione Templates, troverete la descrizione della struttura di diversi template, ognuno con le sue peculiarità, che poi potrete liberamente scaricare da Scribd, uno dei più noti servizi per condividere documentazione.
Leggi questo articolo...
mercoledì 26 agosto 2009
venerdì 21 agosto 2009
Un esempio di comunicazione efficace
Vi segnalo www.writingmatters.typepad.com/blog/, un'ottima fonte d'ispirazione per affinare le nostre capacità nel mare insidioso della business/technical communication. Volete un esempio ? Quante volte ci è capitata una pagina web con il classico ERROR 404 (File/Page Not Found) ...nudo e crudo e null'affatto "user-friendly", specie per gli utenti meno esperti?
Molti tecnici avrebbero molto da imparare su come deve essere comunicato all'utente il comportamento di un'applicazione web.
Ecco un esempio mirabile di come costruire una pagina efficace per "accompagnare" un ERROR 404:
Qui potete valutare l'articolo completo e prendere confidenza con molti altri contenuti interessanti e spero utili per il vostro lavoro.
E poi, per chiudere l'argomento in allegria, ecco 100 pagine divertenti sull'ERROR 404.
Come dire... "ad ognuno il suo"! Leggi questo articolo...
Molti tecnici avrebbero molto da imparare su come deve essere comunicato all'utente il comportamento di un'applicazione web.
Ecco un esempio mirabile di come costruire una pagina efficace per "accompagnare" un ERROR 404:
Qui potete valutare l'articolo completo e prendere confidenza con molti altri contenuti interessanti e spero utili per il vostro lavoro.
E poi, per chiudere l'argomento in allegria, ecco 100 pagine divertenti sull'ERROR 404.
Come dire... "ad ognuno il suo"! Leggi questo articolo...
martedì 18 agosto 2009
La Babele degli acronimi: seconda parte
Come abbiamo visto nel post del 12 Agosto, l'uso degli acronimi è assoggettabile a regole precise, pur tenendo presenti le debite eccezioni. Ora analizziamo altri aspetti.
L'acronimo può essere confuso con "il marchio" di un'azienda.
Un esempio tipico è quello dell'ENEL (Ente Nazionale per l'Energia eLettrica).
Nel marchio di quest'azienda è visibile invece la sigla Enel, con la sola E maiuscola iniziale. Ecco un esempio in cui, se non vi sono possibili ambiguità, si può scrivere ENEL o Enel indifferentemente, in quanto l'uso ha determinato un'equivalenza delle due modalità, con una sostanziale sovrapposizione tra acronimo e marchio. Ma scrivere 'enel' è invece un errore.
Allo stesso modo, è ormai invalso l'uso equivalente di FIAT e Fiat.
Ma se scrivete 'fiat' qualcuno penserà che state scrivendo una parola latina.
Questo meccanismo è comune a moltissimi acronimi, cioè in tutti quei casi in cui l'uso ha ormai sovrapposto l'acronimo e il marchio/sigla equivalente.
Altro caso è quello del LASER (Light Amplification by Stimulated Emission of Radiation), che viene citato anche come Laser o l'equivalente 'laser'; quindi potrete trovare indifferentemente LASER, Laser o laser.
Nel caso della NATO (North Atlantic Treaty Organization) invece, tale meccanismo non si è affermato; troverete sempre scritto NATO e qualsiasi eccezione è un errore.
Questi esempi avvalorano la regola generale: se scrivete ENEL, FIAT, LASER e NATO siete sicuri di non sbagliare. Se usate invece le altre forme, dovete valutare il contesto e la consuetidine ormai consolidata, ma rischiate di commettere errori.
E' invece ormai caduta in disuso la notazione "puntata", in cui le lettere dell'acronimo sono separate dal '.'.
Quindi NATO e non N.A.T.O, LASER e non L.A.S.E.R. e così via.
Abbiamo finito ? No... al prossimo post.
Leggi questo articolo...
L'acronimo può essere confuso con "il marchio" di un'azienda.
Un esempio tipico è quello dell'ENEL (Ente Nazionale per l'Energia eLettrica).
Nel marchio di quest'azienda è visibile invece la sigla Enel, con la sola E maiuscola iniziale. Ecco un esempio in cui, se non vi sono possibili ambiguità, si può scrivere ENEL o Enel indifferentemente, in quanto l'uso ha determinato un'equivalenza delle due modalità, con una sostanziale sovrapposizione tra acronimo e marchio. Ma scrivere 'enel' è invece un errore.
Allo stesso modo, è ormai invalso l'uso equivalente di FIAT e Fiat.
Ma se scrivete 'fiat' qualcuno penserà che state scrivendo una parola latina.
Questo meccanismo è comune a moltissimi acronimi, cioè in tutti quei casi in cui l'uso ha ormai sovrapposto l'acronimo e il marchio/sigla equivalente.
Altro caso è quello del LASER (Light Amplification by Stimulated Emission of Radiation), che viene citato anche come Laser o l'equivalente 'laser'; quindi potrete trovare indifferentemente LASER, Laser o laser.
Nel caso della NATO (North Atlantic Treaty Organization) invece, tale meccanismo non si è affermato; troverete sempre scritto NATO e qualsiasi eccezione è un errore.
Questi esempi avvalorano la regola generale: se scrivete ENEL, FIAT, LASER e NATO siete sicuri di non sbagliare. Se usate invece le altre forme, dovete valutare il contesto e la consuetidine ormai consolidata, ma rischiate di commettere errori.
E' invece ormai caduta in disuso la notazione "puntata", in cui le lettere dell'acronimo sono separate dal '.'.
Quindi NATO e non N.A.T.O, LASER e non L.A.S.E.R. e così via.
Abbiamo finito ? No... al prossimo post.
mercoledì 12 agosto 2009
La Babele degli acronimi: prima parte
"...L'applicazione necessita di almeno 1 GB di RAM. Essa si basa sui più diffusi protocolli e standad aperti (HTTPS, SSL, FTP, LDAP, XML, WSDL, SOAP, ...) e consente di implementare policies conformi alla SOA, nell'ambito di architetture GRC in cui...".
Avete capito qualcosa?
Se non siete dei consulenti del mondo ICT (?!?...un altro acronimo...) probabilmente no.
"The acronyms' hell" è il pane quotidiano di un TW e quasi ogni giorno spuntano nuovi acronimi in ogni settore tecnico.
Nel campo in cui opero, quello dell'Information&Computer Technology (ICT!... ecco che vuol dire!), questo aspetto è particolarmente critico, perchè è praticamente impossibile non ricorrere all'uso degli acronimi; d'altra parte, un loro uso smodato, così come mostrato nell'esempio iniziale, può conferire al testo una cripticità intellegibile solo agli addetti ai lavori.
Ci sono delle regole a cui affidarsi ? Certamente si, ma laddove ci sono delle regole, ci sono anche le relative eccezioni. Come in altri post di questo blog, cercherò di delineare gli elementi essenziali di quest'argomento, senza la pretesa di esaurirlo in ogni suo aspetto.
Un acronimo è una parola formata con le lettere iniziali di determinate parole di una frase o di una definizione.
In una accezione più "lasca", sarà possibile formare un acronimo anche a partire da alcun sillabe, non solo dalle iniziali, del gruppo di parole considerate.
Alcuni esempi di acronimi derivanti dalla definizione "stretta":
- SSL: Secure Socket Layer
- FTP: File Transfer Protocol
- FIGC: Federazione Italiana Gioco Calcio
- FIAT: Fabbrica Italiana Automobili Torino
... ed altri esempi derivanti dalla definizione "lasca":
- XML: eXtensbile Markup Language
- DNA: DeoxyriboNucleic Acid
- EURATOM: EURopean ATOMic Energy Community
La regola fondamentale, CHE NON PUO' MAI ESSERE DISATTESA, è quella che NON SI DEVE USARE MAI UN ACRONIMO senza specificare, alla prima citazione, l'espressione estesa alla quale quell'acronimo si riferisce.
Alcuni esempi?
"... la BCE (Banca Centrale Europea) ha emanato i nuovi valori dei tassi che saranno in vigore per i prossimi 3 mesi. Le aspettative degli analisti, che prevedevano una diminuzione dello 0.25, sono state disattese; il Presidente della BCE ha motivato le scelte effettuate con la necessità...".
Come si vede dall'esempio, si usa l'acronimo BCE e subito dopo, tra parentesi tonde, si indica l'espressione estesa, con le lettere che formano l'acronimo in maiuscolo. Successivamente, si usa l'acronimo senza più specificare la sua espressione estesa.
Altro esempio:
" ... la comunicazione delle credenziali dell'utente avviene su un canale sicuro, secondo le modalità previste dal protocollo SSL (Secure Socket Layer). Un canale SSL consente...".
CI SONO ECCEZIONI A QUESTA REGOLA ?
Si e dipendono dal contesto, nonchè dal "lettore target" a cui state pensando mentre scrivete.
Se state scrivendo un articolo su una rivista di auto e vi riferite al mercato dell'automobile in Italia, potete usare l'acronimo FIAT senza dover citare la sua dizione estesa.
Se state preparando una relazione da leggere ad una riunione di esperti genetisti, potete usare il termine DNA senza altra cautela.
In altri termini, potete usare un acronimo senza accompagnarlo con la sua espressione estesa, SOLO SE NEL CONTESTO IN CUI LO UTILIZZATE non vi è alcun dubbio in merito alla sua interpretazione.
All'inzio del post ho citato un brano tratto da una scheda tecnica di un prodotto software.
Per un esperto di ICT, il brano è abbastanza chiaro ma c'è l'ultimo acronimo, GRC, che può dar luogo a dubbi. GRC vorrà dire... Governance Risk Management and Compliance... oppure ... Governance Risk Control... oppure ... General Review Control... oppure ... ?!?
Ecco un bell'esempio in cui alcuni acronimi (SSL, XML, SOAP, ...) possono essere citati senza alcuna cautela, perchè siamo certi che il lettore target per il quale scriviamo non avrà dubbi nell'interpretarli, mentre altri vanno accompagnati dalla corretta espressione estesa (Governance Risk Management and Compliance).
Abbiamo esaurito l'argomento ? Ovviamente no... al prossimo post per esplorare altri aspetti degni di attenzione.
Leggi questo articolo...
Avete capito qualcosa?
Se non siete dei consulenti del mondo ICT (?!?...un altro acronimo...) probabilmente no.
"The acronyms' hell" è il pane quotidiano di un TW e quasi ogni giorno spuntano nuovi acronimi in ogni settore tecnico.
Nel campo in cui opero, quello dell'Information&Computer Technology (ICT!... ecco che vuol dire!), questo aspetto è particolarmente critico, perchè è praticamente impossibile non ricorrere all'uso degli acronimi; d'altra parte, un loro uso smodato, così come mostrato nell'esempio iniziale, può conferire al testo una cripticità intellegibile solo agli addetti ai lavori.
Ci sono delle regole a cui affidarsi ? Certamente si, ma laddove ci sono delle regole, ci sono anche le relative eccezioni. Come in altri post di questo blog, cercherò di delineare gli elementi essenziali di quest'argomento, senza la pretesa di esaurirlo in ogni suo aspetto.
Un acronimo è una parola formata con le lettere iniziali di determinate parole di una frase o di una definizione.
In una accezione più "lasca", sarà possibile formare un acronimo anche a partire da alcun sillabe, non solo dalle iniziali, del gruppo di parole considerate.
Alcuni esempi di acronimi derivanti dalla definizione "stretta":
- SSL: Secure Socket Layer
- FTP: File Transfer Protocol
- FIGC: Federazione Italiana Gioco Calcio
- FIAT: Fabbrica Italiana Automobili Torino
... ed altri esempi derivanti dalla definizione "lasca":
- XML: eXtensbile Markup Language
- DNA: DeoxyriboNucleic Acid
- EURATOM: EURopean ATOMic Energy Community
La regola fondamentale, CHE NON PUO' MAI ESSERE DISATTESA, è quella che NON SI DEVE USARE MAI UN ACRONIMO senza specificare, alla prima citazione, l'espressione estesa alla quale quell'acronimo si riferisce.
Alcuni esempi?
"... la BCE (Banca Centrale Europea) ha emanato i nuovi valori dei tassi che saranno in vigore per i prossimi 3 mesi. Le aspettative degli analisti, che prevedevano una diminuzione dello 0.25, sono state disattese; il Presidente della BCE ha motivato le scelte effettuate con la necessità...".
Come si vede dall'esempio, si usa l'acronimo BCE e subito dopo, tra parentesi tonde, si indica l'espressione estesa, con le lettere che formano l'acronimo in maiuscolo. Successivamente, si usa l'acronimo senza più specificare la sua espressione estesa.
Altro esempio:
" ... la comunicazione delle credenziali dell'utente avviene su un canale sicuro, secondo le modalità previste dal protocollo SSL (Secure Socket Layer). Un canale SSL consente...".
CI SONO ECCEZIONI A QUESTA REGOLA ?
Si e dipendono dal contesto, nonchè dal "lettore target" a cui state pensando mentre scrivete.
Se state scrivendo un articolo su una rivista di auto e vi riferite al mercato dell'automobile in Italia, potete usare l'acronimo FIAT senza dover citare la sua dizione estesa.
Se state preparando una relazione da leggere ad una riunione di esperti genetisti, potete usare il termine DNA senza altra cautela.
In altri termini, potete usare un acronimo senza accompagnarlo con la sua espressione estesa, SOLO SE NEL CONTESTO IN CUI LO UTILIZZATE non vi è alcun dubbio in merito alla sua interpretazione.
All'inzio del post ho citato un brano tratto da una scheda tecnica di un prodotto software.
Per un esperto di ICT, il brano è abbastanza chiaro ma c'è l'ultimo acronimo, GRC, che può dar luogo a dubbi. GRC vorrà dire... Governance Risk Management and Compliance... oppure ... Governance Risk Control... oppure ... General Review Control... oppure ... ?!?
Ecco un bell'esempio in cui alcuni acronimi (SSL, XML, SOAP, ...) possono essere citati senza alcuna cautela, perchè siamo certi che il lettore target per il quale scriviamo non avrà dubbi nell'interpretarli, mentre altri vanno accompagnati dalla corretta espressione estesa (Governance Risk Management and Compliance).
Abbiamo esaurito l'argomento ? Ovviamente no... al prossimo post per esplorare altri aspetti degni di attenzione.
Leggi questo articolo...
mercoledì 29 luglio 2009
Eccomi a voi con questa mia a dirvi...
..."ADDIRVI... tutta una parola!", come diceva il principe Antonio De Curtis, in arte Totò, nella celeberrima e immortale scena della redazione della lettera, con Peppino De Filippo, in "Totò, Peppino e la malafemmina".
Dunque, a dirvi... che sono tornato dopo due settimane di corso d'Inglese full-immersion in cui, mentre tentavo di migliorare la mia conoscenza della lingua, ho abbozzato una serie di idee per molti nuovi post che vi proporrò prossimamente.
Per ora... un mini set di semplici acronimi che si possono usare (ma senza esagerare...) in una mail professionale, specialmente se avete maturato una particolare confidenza con il destinatario della medesima:
Presto dedicherò un post proprio a questo argomento, particolarmente critico nell'ambito dell'Information and Computer Technology, ove gli acronimi proliferano come i funghi nel bosco a Settembre. Leggi questo articolo...
Dunque, a dirvi... che sono tornato dopo due settimane di corso d'Inglese full-immersion in cui, mentre tentavo di migliorare la mia conoscenza della lingua, ho abbozzato una serie di idee per molti nuovi post che vi proporrò prossimamente.
Per ora... un mini set di semplici acronimi che si possono usare (ma senza esagerare...) in una mail professionale, specialmente se avete maturato una particolare confidenza con il destinatario della medesima:
- ASAP as soon as possible
- NRN no reply necessary
- FYI for your info
- RFI request for information
- PCM please call me
- LMK let me know
Presto dedicherò un post proprio a questo argomento, particolarmente critico nell'ambito dell'Information and Computer Technology, ove gli acronimi proliferano come i funghi nel bosco a Settembre. Leggi questo articolo...
mercoledì 15 luglio 2009
Quali documenti... per quale prodotto?
Nel post del 2 Luglio ho fornito una roadmap minima attraverso la quale è possibile pianificare la produzione della documentazione di un'azienda. In funzione del contesto, tale roadmap può essere arricchita e diversificata.
Ma supponendo di partire da zero, gli elementi indicati sono da ritenersi gli elementi di base necessari da cui possiamo partire per organizzare il nostro lavoro.
A questo punto, chiediamoci COSA dobbiamo documentare e QUALI/QUANTI documenti dobbiamo mettere in cantiere a tale scopo.
Io lavoro in un'azienda IT che realizza prodotti software, in un'area di mercato altamente specializzata. Nel mio caso, per documentare un singolo prodotto, è sempre necessario realizzare ALMENO i seguenti documenti:
- BROCHURE: è il documento di marketing che fornisce, al cliente potenziale, le prime informazioni fondamentali sul prodotto.
- TECHNICAL SPECIFICATION: è il documento di sintesi che racchiude tutte le informazioni tecniche necessarie sul prodotto.
- INSTALLATION MANUAL: è il documento che fornisce tutte le informazioni per installare ed eventualmene configurare il prodotto.
- GETTING STARTED MANUAL (QUICK START GUIDE): è il documento che consente di prendere confidenza rapidamente con tutte le funzionalità di base del prodotto.
- ADMINISTRATION MANUAL: è un documento che contiene tutte le informazioni dettagliate, spesso in modalità Tutorial, rivolto ad un utente "evoluto", destinato al ruolo di Amministratore del prodotto e che quindi deve conoscere ogni aspetto del medesimo.
Perchè li ho elencati con la dizione inglese ?
Perchè abbiamo deciso di scrivere la documentazione di prodotto in inglese, visto che il mercato al quale ci rivolgiamo non è limitato all'interno dei confini nazionali.
Poi è spesso necessario mettere a punto altri documenti quali:
- USER MANUAL: è un documento rivolto ad un utente che deve usare il prodotto (tipicamente un sottoinsieme delle funzionalità disponibili nel prodotto) ma non ha le esigenze dell'utente a cui è dedicato l'Administrator Manual.
- INTEGRATION MANUAL: è un documento che descrive in che modo è possibile integrare il prodotto in un'architettura software pre-esistente, o l'aggiornamento del prodotto rispetto ad una versione precedente gia installata nel sistema ospite.
- API REFERENCE MANUAL: è un documento, finalizzato ad un tecnico programmatore, che descrive le librerie software eventualmente associate al prodotto.
Inoltre, all'interno delle applicazioni software, è necessario predisporre un HELP in formato HTML, i cui contenuti possono essere mutuati da uno o più manuali tra quelli elencati ma che richiedono un lavoro di filtro e formattazione che non può essere realizzato attraverso un banale
e meccanico "copia e incolla" di quanto già realizzato.
Ogni singolo prodotto deve poi essere testato e collaudato e questo richiede lo sviluppo di un'appropriata DOCUMENTAZIONE DI COLLAUDO.
C'è tutto? Certamento no... ma c'è abbastanza.
E TUTTO QUESTO PER OGNI SINGOLO PRODOTTO!
Ma se invece di un prodotto software dobbiamo documentare un video-registratore?
In tal caso l'INSTALLATION MANUAL e la QUICK START GUIDE dovrebbero essere sufficenti, almeno per iniziare ad usare il prodotto. Ma deve essere predisposto anche lo USER MANUAL per i clienti più esigenti, che vogliono indagare anche le funzionalità meno comuni.
L'altra settimana ho comprato una piscina di plastica da giardino... di quelle per far giocare i bambini nei giorni più torridi dell'estate; c'era il MANUALE DI MONTAGGIO in forma cartacea ed un CD ROM contenente un filmato di presentazione in formato AVI, in cui sono illustrate
accuratamente tutte le fasi di montaggio e manutenzione.
Insomma, ogni prodotto richiede un set di documenti ben preciso, in base alla sua natura, all'uso che se ne deve fare e a chi lo dovrà utilizzare.
E' ASSOLUTAMENTE NECESSARIO STABILIRE CON ATTENZIONE la manualistica da realizzare per ogni prodotto, nelle diverse forme possibili.
E QUANDO REALIZZIAMO UN PROGETTO PER UN CERTO CLIENTE?
Un progetto si sviluppa attraverso diverse fasi ben distinte; generalmente, ogni fase prevede un certo tipo di documentazione.
Ad esempio, nella fase iniziale di un progetto software, viene redatto il DOCUMENTO DI ASSESSMENT, in cui viene delineata l'analisi del progetto e le soluzioni funzionali richieste, sulla base delle specifiche caratteristiche tecniche e delle logiche di business proprie del cliente,
nonchè di altri vincoli in essere (moduli software/hardware già posseduti dal cliente, prescrizioni legislative, ecc...).
Nella fase finale del progetto, quando l'architettura software viene rilasciata in esercizio, viene prodotto il MANUALE DI ESERCIBILITA', che racchiude tutte le informazioni tecniche necessarie alla gestione dell'architettura.
Se l'architettura prevede l'integrazione di uno più prodotti, dovrà essere rilasciata tutta la necessaria documentazione relativa ad ogni singolo prodotto e l'eventuale sopracitato INTEGRATION MANUAL.
Se poi sono state introdotte delle personalizzazioni "ad-hoc", anche tali moduli personalizzati dovranno essere documentati con manuali dedicati.
Il DOCUMENTO DI ASSESSMENT e il MANUALE DI ESERCIBILITA' possono essere idealmente considerati il documento iniziale e il documento finale di un progetto sofware; lungo lo sviluppo del progetto potranno poi essere rilasciati un gran numero di documenti intermedi.
Analoghe considerazioni possono essere svolte in altri ambiti tecnici.
La DOCUMENTAZIONE DI PROGETTO riveste una sua specificità ed è ancor meno schematizzabile rispetto a quella che dobbiamo sviluppare per un prodotto. La stretta collaborazione tra i diversi progettisti ed il TW, nonchè l'esperienza di tali soggetti nella gestione delle diverse fasi del progetto, sono elementi essenziali per poter sviluppare dei buoni documenti.
In conclusione, spero di avervi convinto, pur non potendo esaurire l'argomento in un singolo post, che la capacità di pianificare COSA si deve fare, PRIMA DI INIZIARE "A FARE", rappresenta il fidato "filo di Arianna" che ci garantisce di non perderci nel labirinto.
Leggi questo articolo...
Ma supponendo di partire da zero, gli elementi indicati sono da ritenersi gli elementi di base necessari da cui possiamo partire per organizzare il nostro lavoro.
A questo punto, chiediamoci COSA dobbiamo documentare e QUALI/QUANTI documenti dobbiamo mettere in cantiere a tale scopo.
Io lavoro in un'azienda IT che realizza prodotti software, in un'area di mercato altamente specializzata. Nel mio caso, per documentare un singolo prodotto, è sempre necessario realizzare ALMENO i seguenti documenti:
- BROCHURE: è il documento di marketing che fornisce, al cliente potenziale, le prime informazioni fondamentali sul prodotto.
- TECHNICAL SPECIFICATION: è il documento di sintesi che racchiude tutte le informazioni tecniche necessarie sul prodotto.
- INSTALLATION MANUAL: è il documento che fornisce tutte le informazioni per installare ed eventualmene configurare il prodotto.
- GETTING STARTED MANUAL (QUICK START GUIDE): è il documento che consente di prendere confidenza rapidamente con tutte le funzionalità di base del prodotto.
- ADMINISTRATION MANUAL: è un documento che contiene tutte le informazioni dettagliate, spesso in modalità Tutorial, rivolto ad un utente "evoluto", destinato al ruolo di Amministratore del prodotto e che quindi deve conoscere ogni aspetto del medesimo.
Perchè li ho elencati con la dizione inglese ?
Perchè abbiamo deciso di scrivere la documentazione di prodotto in inglese, visto che il mercato al quale ci rivolgiamo non è limitato all'interno dei confini nazionali.
Poi è spesso necessario mettere a punto altri documenti quali:
- USER MANUAL: è un documento rivolto ad un utente che deve usare il prodotto (tipicamente un sottoinsieme delle funzionalità disponibili nel prodotto) ma non ha le esigenze dell'utente a cui è dedicato l'Administrator Manual.
- INTEGRATION MANUAL: è un documento che descrive in che modo è possibile integrare il prodotto in un'architettura software pre-esistente, o l'aggiornamento del prodotto rispetto ad una versione precedente gia installata nel sistema ospite.
- API REFERENCE MANUAL: è un documento, finalizzato ad un tecnico programmatore, che descrive le librerie software eventualmente associate al prodotto.
Inoltre, all'interno delle applicazioni software, è necessario predisporre un HELP in formato HTML, i cui contenuti possono essere mutuati da uno o più manuali tra quelli elencati ma che richiedono un lavoro di filtro e formattazione che non può essere realizzato attraverso un banale
e meccanico "copia e incolla" di quanto già realizzato.
Ogni singolo prodotto deve poi essere testato e collaudato e questo richiede lo sviluppo di un'appropriata DOCUMENTAZIONE DI COLLAUDO.
C'è tutto? Certamento no... ma c'è abbastanza.
E TUTTO QUESTO PER OGNI SINGOLO PRODOTTO!
Ma se invece di un prodotto software dobbiamo documentare un video-registratore?
In tal caso l'INSTALLATION MANUAL e la QUICK START GUIDE dovrebbero essere sufficenti, almeno per iniziare ad usare il prodotto. Ma deve essere predisposto anche lo USER MANUAL per i clienti più esigenti, che vogliono indagare anche le funzionalità meno comuni.
L'altra settimana ho comprato una piscina di plastica da giardino... di quelle per far giocare i bambini nei giorni più torridi dell'estate; c'era il MANUALE DI MONTAGGIO in forma cartacea ed un CD ROM contenente un filmato di presentazione in formato AVI, in cui sono illustrate
accuratamente tutte le fasi di montaggio e manutenzione.
Insomma, ogni prodotto richiede un set di documenti ben preciso, in base alla sua natura, all'uso che se ne deve fare e a chi lo dovrà utilizzare.
E' ASSOLUTAMENTE NECESSARIO STABILIRE CON ATTENZIONE la manualistica da realizzare per ogni prodotto, nelle diverse forme possibili.
E QUANDO REALIZZIAMO UN PROGETTO PER UN CERTO CLIENTE?
Un progetto si sviluppa attraverso diverse fasi ben distinte; generalmente, ogni fase prevede un certo tipo di documentazione.
Ad esempio, nella fase iniziale di un progetto software, viene redatto il DOCUMENTO DI ASSESSMENT, in cui viene delineata l'analisi del progetto e le soluzioni funzionali richieste, sulla base delle specifiche caratteristiche tecniche e delle logiche di business proprie del cliente,
nonchè di altri vincoli in essere (moduli software/hardware già posseduti dal cliente, prescrizioni legislative, ecc...).
Nella fase finale del progetto, quando l'architettura software viene rilasciata in esercizio, viene prodotto il MANUALE DI ESERCIBILITA', che racchiude tutte le informazioni tecniche necessarie alla gestione dell'architettura.
Se l'architettura prevede l'integrazione di uno più prodotti, dovrà essere rilasciata tutta la necessaria documentazione relativa ad ogni singolo prodotto e l'eventuale sopracitato INTEGRATION MANUAL.
Se poi sono state introdotte delle personalizzazioni "ad-hoc", anche tali moduli personalizzati dovranno essere documentati con manuali dedicati.
Il DOCUMENTO DI ASSESSMENT e il MANUALE DI ESERCIBILITA' possono essere idealmente considerati il documento iniziale e il documento finale di un progetto sofware; lungo lo sviluppo del progetto potranno poi essere rilasciati un gran numero di documenti intermedi.
Analoghe considerazioni possono essere svolte in altri ambiti tecnici.
La DOCUMENTAZIONE DI PROGETTO riveste una sua specificità ed è ancor meno schematizzabile rispetto a quella che dobbiamo sviluppare per un prodotto. La stretta collaborazione tra i diversi progettisti ed il TW, nonchè l'esperienza di tali soggetti nella gestione delle diverse fasi del progetto, sono elementi essenziali per poter sviluppare dei buoni documenti.
In conclusione, spero di avervi convinto, pur non potendo esaurire l'argomento in un singolo post, che la capacità di pianificare COSA si deve fare, PRIMA DI INIZIARE "A FARE", rappresenta il fidato "filo di Arianna" che ci garantisce di non perderci nel labirinto.
Leggi questo articolo...
domenica 12 luglio 2009
14 Luglio Sciopero dei Blogger contro il DDL Alfano
L'artigiano di Babele aderisce alla protesta dei blogger organizzata da Diritto alla Rete contro il DDL Alfano.
Non è nostra intenzione inserire argomenti di politica in questo forum, ma non condividiamo questo decreto che consideriamo pericoloso per la libertà di espressione.
Ricordiamo che L'artigiano di Babele, NON E’ UNA TESTATA GIORNALISTICA, in quanto viene aggiornato senza alcuna periodicità. Non può pertanto considerarsi un prodotto editoriale ai sensi della legge n. 62 del 7.03.2001, ma il decreto non si rivolge solo alle testate giornalistiche ma a qualsiasi sito informatico.
Le perplessità che abbiamo riguardano l’obbligo di rettifica entro le 48 ore dalla richiesta di un’eventuale soggetto offeso dalle dichiarazioni pubblicate da un sito informatico:
Art. 15.
(…) «Per le trasmissioni radiofoniche o televisive, le dichiarazioni o
le rettifiche sono effettuate ai sensi dell’articolo 32 del testo
unico della radiotelevisione, di cui al decreto legislativo 31 luglio
2005, n. 177.
Per i siti informatici, le dichiarazioni o le rettifiche
sono pubblicate, entro quarantotto ore dalla richiesta, con le stesse
caratteristiche grafiche, la stessa metodologia di accesso al sito e
la stessa visibilità della notizia cui si riferiscono»;
Per come è stato scritto, darebbe modo a chiunque non fosse d’accordo con una frase o un post di richiedere la rettifica, vanificando così il pensiero dell’autore.
Se non vi sarà una rettifica, una smentita sul sito, il gestore o il proprietario dello stesso pagherà una multa che può arrivare fino a circa 13.000 euro. Questo vale non solo per i blogger, ma anche per i forum e quindi anche per i post che i lettori inviano.
Benchè in questo sito non esprimiamo pareri negativi su aziende o persone, il decreto ci sembra comunque pericoloso per la libertà di pensiero, in generale, anche per gli altri blogger.
Le leggi sulla diffamazione esistono già ma è sempre un giudice a garantire che quanto dice il presunto offeso sia reale o semplice voglia di creare danno o “chiudere la bocca” ad un’altra persona.
Il 14 Luglio vi sarà una manifestazione a Roma, in Piazza Navona, con i Blogger imbavagliati per una protesta pacifica.
Leggi questo articolo...
sabato 4 luglio 2009
Una perla dal blog di Luisa Carrada
Oggi un post breve breve per segnalarvi una "perla", molto attinente alle problematiche di cui mi occupo.
Lo trovate su http://mestierediscrivere.splinder.com, in data 1° Luglio 2009.
Questo blog è un "luogo delle delizie" per chi si interessa di scrittura professionale e affini e l'ho già segnalato nella categoria DA VISITARE, che trovate in questa pagina, in basso a destra.
Luisa Carrada è una "guru" in questo campo e nel mio percorso da autodidatta, ho imparato molto "saccheggiando" i suoi suggerimenti.
Pur non conoscendola di persona, ho avuto modo di ringraziarla via mail per tutto quello che mi ha insegnato indirettamente, attraverso la lettura dei suoi post e la biblioteca dei "quaderni".
C'è molto da imparare... approfittatene. Leggi questo articolo...
Lo trovate su http://mestierediscrivere.splinder.com, in data 1° Luglio 2009.
Questo blog è un "luogo delle delizie" per chi si interessa di scrittura professionale e affini e l'ho già segnalato nella categoria DA VISITARE, che trovate in questa pagina, in basso a destra.
Luisa Carrada è una "guru" in questo campo e nel mio percorso da autodidatta, ho imparato molto "saccheggiando" i suoi suggerimenti.
Pur non conoscendola di persona, ho avuto modo di ringraziarla via mail per tutto quello che mi ha insegnato indirettamente, attraverso la lettura dei suoi post e la biblioteca dei "quaderni".
C'è molto da imparare... approfittatene. Leggi questo articolo...
giovedì 2 luglio 2009
Pianificare la produzione della documentazione
Uno degli errori più grossolani che si possono commettere nella produzione della documentazione aziendale, consiste nel NON PIANIFICARE tutte le fasi del processo di produzione. Se siete chiamati sporadicamente a realizzare un documento, potete anche pensare di dare fondo al vostro talento con tutto il corredo di estemporaneità che può derivarne. Ma il talento è nulla senza la tecnica e la capacità di pianificare in ogni aspetto tale processo di produzione. Questo aspetto diviene via via più decisivo in proporzione diretta alla quantità e alla qualità dei documenti che siete chiamati a produrre.
Come sempre, non esiste uno schema universale ed esaustivo che possa andar bene per ogni azienda o contesto professionale.
Esistono però dei passaggi chiave che devono essere sempre tenuti ben presenti e che possono trovare una valida applicabilità nella gran parte delle situazioni.
L'elenco che vi propongo identifica un "set minimo" di attività che può essere arricchito in base alle vostre esigenze:
DEFINIRE UN'ELENCO DI DOCUMENTI CHE ACCOMPAGNANO OGNI PRODOTTO
DEFINIRE UN INSIEME DI TEMPLATE PER OGNI TIPO DOCUMENTO
DEFINIRE UNA CONVENZIONE DI FILE-NAMING PER LA DOCUMENTAZIONE
INDIVIDUARE IL REPOSITORY DELLA DOCUMENTAZIONE AZIENDALE
ORGANIZZARE LA DOCUMENTAZIONE NEL REPOSITORY PRESCELTO
DEFINIRE I CRITERI DI ACCESSO/DISTRIBUZIONE DELLA DOCUMENTAZIONE
NESSUNO DI TALI PUNTI PUO' ESSERE OMESSO nella pianificazione del processo di produzione della documentazione tecnica di un'azienda.
Ovviamente, non è obbligatorio seguire in modo rigidamente sequenziale i passi sopraindicati.
Come ho già raccontato nel post precedente, quando ho cominciato il mio percorso di TW, ho definito per prima cosa una CONVENZIONE PER IL NAMING della documentazione; avevo una priorità assoluta di classificare quanto era stato prodotto, senza alcuna pianificazione, nei precedenti 4 anni e questa prima scelta mi ha facilitato molto il lavoro.
Invece, la definizione dei TEMPLATE è stato un processo progressivo e stratificato, sviluppato per approssimazioni successive e ancora oggi è ben lungi dall'essere terminato.
Nei prossimi post mi riprometto di approfondire i dettagli che mi sembrano più interessanti, inerenti al "set minimo" che vi ho segnalato.
Leggi questo articolo...
Come sempre, non esiste uno schema universale ed esaustivo che possa andar bene per ogni azienda o contesto professionale.
Esistono però dei passaggi chiave che devono essere sempre tenuti ben presenti e che possono trovare una valida applicabilità nella gran parte delle situazioni.
L'elenco che vi propongo identifica un "set minimo" di attività che può essere arricchito in base alle vostre esigenze:
DEFINIRE UN'ELENCO DI DOCUMENTI CHE ACCOMPAGNANO OGNI PRODOTTO
DEFINIRE UN INSIEME DI TEMPLATE PER OGNI TIPO DOCUMENTO
DEFINIRE UNA CONVENZIONE DI FILE-NAMING PER LA DOCUMENTAZIONE
INDIVIDUARE IL REPOSITORY DELLA DOCUMENTAZIONE AZIENDALE
ORGANIZZARE LA DOCUMENTAZIONE NEL REPOSITORY PRESCELTO
DEFINIRE I CRITERI DI ACCESSO/DISTRIBUZIONE DELLA DOCUMENTAZIONE
NESSUNO DI TALI PUNTI PUO' ESSERE OMESSO nella pianificazione del processo di produzione della documentazione tecnica di un'azienda.
Ovviamente, non è obbligatorio seguire in modo rigidamente sequenziale i passi sopraindicati.
Come ho già raccontato nel post precedente, quando ho cominciato il mio percorso di TW, ho definito per prima cosa una CONVENZIONE PER IL NAMING della documentazione; avevo una priorità assoluta di classificare quanto era stato prodotto, senza alcuna pianificazione, nei precedenti 4 anni e questa prima scelta mi ha facilitato molto il lavoro.
Invece, la definizione dei TEMPLATE è stato un processo progressivo e stratificato, sviluppato per approssimazioni successive e ancora oggi è ben lungi dall'essere terminato.
Nei prossimi post mi riprometto di approfondire i dettagli che mi sembrano più interessanti, inerenti al "set minimo" che vi ho segnalato.
Leggi questo articolo...
domenica 21 giugno 2009
Regole di Naming per la documentazione
Quando nel 2005 iniziai il mio lavoro, per prima cosa dovetti classificare centinaia di documenti realizzati in azienda, all'insegna della più completa anarchia, nei precedenti 4 anni.
La casistica disponibile era sorprendente:
Non esistono indicazioni univoche su come impostare una regola di Naming della documentazione aziendale. Anche i guru del Technical Writing di matrice anglosassone, forniscono indicazioni assolutamente ragionevoli e ispirate a principi di "buon senso" che ognuno di noi può identificare autonomamente e deve essere in grado di adattare alla propria realtà lavorativa.
IL PRINCIPIO FONDAMENTALE è:
NON SI INIZIA A CLASSIFICARE NULLA SENZA UNA REGOLA DI NAMING.
La regola che ho adottato e che è ancora in vigore, è estremamente semplice e si struttura in questo modo:
ACRONIMO PRODOTTO/PROGETTO-VERSIONE PRODOTTO/PROGETTO-NOME MANUALE-VERSIONE DOCUMENTO-NOME AZIENDA/CLIENTE
Vediamo due esempi:
NMM-210-Installation_Manual-100-EngNetServices.pdf
Questo nome indica l' Installation Manual del prodotto Network Monitoring Module (NMM), giunto alla versione 2.1.0; la versione del documento è la 1.0.0 e il nome dell'azienda che lo produce è EngNetServices.
PPWC-340-Administration_Manual-120-ENELERGSUN.doc
Questo nome indica l'Administration Manual del prodotto Profile Provisioning Web Console (PPWC), sviluppato per il cliente ENELERGSUN, giunto alla versione 3.4.0; la versione del documento è la 1.2.0.
Come vedete, non è necessaria un'intelligenza cartesiana per definire una regola di Naming.
Tipicamente, ne fanno uso le aziende di alto livello e ben organizzate, in cui la produzione e la classificazione della documentazione rappresenta un'elemento importante della filosofia di business.
In particolare, le aziende che si sottopongono ad un percorso di certificazione di qualità dei processi produttivi, adottano regole di Naming anche molto più articolate di quella che ho adottato io.
Ovviamente questa regola non è la migliore possibile ma funziona abbastanza bene.
In questo modo i nomi apposti ai documenti divengono "parlanti", nel senso appena illustrato.
L'efficacia di una regola di Naming dipende anche dal contesto.
L'ACRONIMO PRODOTTO/PROGETTO ha più senso in un'ottica "interna" che esterna.
Quindi questa regola va benissimo per la documentazione tecnica, molto meno per la documentazione di Marketing, dove anche il nome del documento deve, in genere, essere più "esplicito".
Nulla vieta di adottare 2 o 3 regole di Naming distinte, all'interno dell'azienda, purchè siano ben specificate e note a tutti gli appartenenti della medesima.
Io preferisco una regola unica, semplice e flessibile quanto basta.
Ma ovviamente e come sempre, non si può avere tutto dalla vita; in quest'ottica vediamo in che modo si potrebbe modificare la regola illustrata se volessimo ottenere nomi "più compatti" (ma meno "parlanti").
Immaginiamo di assegnare un codice numerico a tutte le tipologie di documentazione previste per un generico prodotto:
001 - Technical Specification
002 - Installation Manual
003 - Getting Started Manual
004 - Administration Manual
005 - Product Manual
006 - Developer Manual
Riprendiamo gli esempi precedenti:
NMM-210-Installation_Manual-100-EngNetServices.pdf
NMM-210-002-100-EngNetServices.pdf
PPWC-340-Administration_Manual-120-ENELERGSUN.doc
PPWC-340-004-120-ENELERGSUN.doc
Come vedete, la regola induce a nomi più compatti ma meno intellegibili.
Ovviamente, una regola di Naming può essere utile anche per classificare i vostri documenti privati.
Come sempre, vi sottopongo la mia esperienza senza la pretesa di proporre formule esaustive, ma con l'intenzione di fornirvi spunti utili per una migliore gestione della documentazione.
Usate le regole di Naming... ne trarrete solo vantaggi.
Leggi questo articolo...
La casistica disponibile era sorprendente:
- documenti sostanzialmente identici salvati con nomi diversi
- documenti notevolmente diversi salvati con lo stesso nome
- documenti relativi allo stesso prodotto ma concettualmente diversi (la Scheda Tecnica, il Manuale d'Installazione, il Manuale dell'Amministratore,...) anch'essi identificati dallo stesso nome
- documenti relativi a versioni diverse dello stesso prodotto salvati con nomi "mimetici" rispetto alla versione
- documenti salvati con nomi assolutamente scorrelati dal contenuto
- altro ancora... che al sol pensier ancor mi dole il cor...
Non esistono indicazioni univoche su come impostare una regola di Naming della documentazione aziendale. Anche i guru del Technical Writing di matrice anglosassone, forniscono indicazioni assolutamente ragionevoli e ispirate a principi di "buon senso" che ognuno di noi può identificare autonomamente e deve essere in grado di adattare alla propria realtà lavorativa.
IL PRINCIPIO FONDAMENTALE è:
NON SI INIZIA A CLASSIFICARE NULLA SENZA UNA REGOLA DI NAMING.
La regola che ho adottato e che è ancora in vigore, è estremamente semplice e si struttura in questo modo:
ACRONIMO PRODOTTO/PROGETTO-VERSIONE PRODOTTO/PROGETTO-NOME MANUALE-VERSIONE DOCUMENTO-NOME AZIENDA/CLIENTE
Vediamo due esempi:
NMM-210-Installation_Manual-100-EngNetServices.pdf
Questo nome indica l' Installation Manual del prodotto Network Monitoring Module (NMM), giunto alla versione 2.1.0; la versione del documento è la 1.0.0 e il nome dell'azienda che lo produce è EngNetServices.
PPWC-340-Administration_Manual-120-ENELERGSUN.doc
Questo nome indica l'Administration Manual del prodotto Profile Provisioning Web Console (PPWC), sviluppato per il cliente ENELERGSUN, giunto alla versione 3.4.0; la versione del documento è la 1.2.0.
Come vedete, non è necessaria un'intelligenza cartesiana per definire una regola di Naming.
Tipicamente, ne fanno uso le aziende di alto livello e ben organizzate, in cui la produzione e la classificazione della documentazione rappresenta un'elemento importante della filosofia di business.
In particolare, le aziende che si sottopongono ad un percorso di certificazione di qualità dei processi produttivi, adottano regole di Naming anche molto più articolate di quella che ho adottato io.
Ovviamente questa regola non è la migliore possibile ma funziona abbastanza bene.
In questo modo i nomi apposti ai documenti divengono "parlanti", nel senso appena illustrato.
L'efficacia di una regola di Naming dipende anche dal contesto.
L'ACRONIMO PRODOTTO/PROGETTO ha più senso in un'ottica "interna" che esterna.
Quindi questa regola va benissimo per la documentazione tecnica, molto meno per la documentazione di Marketing, dove anche il nome del documento deve, in genere, essere più "esplicito".
Nulla vieta di adottare 2 o 3 regole di Naming distinte, all'interno dell'azienda, purchè siano ben specificate e note a tutti gli appartenenti della medesima.
Io preferisco una regola unica, semplice e flessibile quanto basta.
Ma ovviamente e come sempre, non si può avere tutto dalla vita; in quest'ottica vediamo in che modo si potrebbe modificare la regola illustrata se volessimo ottenere nomi "più compatti" (ma meno "parlanti").
Immaginiamo di assegnare un codice numerico a tutte le tipologie di documentazione previste per un generico prodotto:
001 - Technical Specification
002 - Installation Manual
003 - Getting Started Manual
004 - Administration Manual
005 - Product Manual
006 - Developer Manual
Riprendiamo gli esempi precedenti:
NMM-210-Installation_Manual-100-EngNetServices.pdf
NMM-210-002-100-EngNetServices.pdf
PPWC-340-Administration_Manual-120-ENELERGSUN.doc
PPWC-340-004-120-ENELERGSUN.doc
Come vedete, la regola induce a nomi più compatti ma meno intellegibili.
Ovviamente, una regola di Naming può essere utile anche per classificare i vostri documenti privati.
Come sempre, vi sottopongo la mia esperienza senza la pretesa di proporre formule esaustive, ma con l'intenzione di fornirvi spunti utili per una migliore gestione della documentazione.
Usate le regole di Naming... ne trarrete solo vantaggi.
Leggi questo articolo...
Iscriviti a:
Post (Atom)
