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:

• 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

Prendo spunto da questa idea per sottolineare che l'uso degli acronimi, nell'ambito della Business Communication, è soggetto a delle regole ben codificate, che in quanto tali possono però contemplare delle eccezioni.

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...

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...

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...

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...

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...