Manuali tecnici: perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti?

  • 302 views
Uploaded on

Punti di debolezza della documentazione tecnica gestita manualmente, cresciuti bisogni informativi dei destinatari, normative, standard e best practices: viaggio alla scoperta di motivi e metodi per …

Punti di debolezza della documentazione tecnica gestita manualmente, cresciuti bisogni informativi dei destinatari, normative, standard e best practices: viaggio alla scoperta di motivi e metodi per strutturare i contenuti e adottare con successo sistemi CMS (Content Management Systems)

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
302
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
13
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.itPerché passare dalla scrittura “free style”alla gestione strutturata dei contenuti?Punti di debolezza della documentazione tecnica, cresciuti bisogni informativi deidestinatari, normative, standard e best practices: viaggio alla scoperta di motivi emetodi per strutturare i contenuti e adottare con successo sistemi CMS (ContentManagement Systems)SommarioPremessa............................................................................................................................................................................ 2I vincoli del “free style” ........................................................................................................................................................ 2Punti di debolezza della documentazione tecnica “free style” ......................................................................................... 2Bisogni informativi dei destinatari della comunicazione tecnica....................................................................................... 3Normativa, standard e best practices .............................................................................................................................. 4Vantaggi della gestione strutturata dei contenuti e dell’adozione di CMS ........................................................................... 5La tecnologia da sola non basta.......................................................................................................................................... 7Conclusione ........................................................................................................................................................................ 81Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 2. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.itPremessaK. Halvorson e M. Rech (Content Strategy per il web. Icontenuti fanno la differenza, Pearson, Milano, Torino, 2013,p. 122) riportano un’interessante citazione dell’esperta dicontent strategy Karen McGrane:… dobbiamo iniziare a pensare ai contenuti come aqualcosa, che vive a prescindere dalle piattaforme dipubblicazione. Non possiamo immaginare laspetto deicontenuti in uno specifico documento, in una pagina o in unaschermata. Dobbiamo invece strutturare i contenuti perpoterli riusare.Ora, il contenuto strutturato non è una novità, ma è semprestato posizionato come un problema di tecnologia ... Ma nonsi tratta di un problema di tecnologia: è un problema distrategia. Quali sono gli oggetti contenuto essenziali con cuiabbiamo a che fare? Quali metadati ci servono perorganizzarli in modo efficace? Quali sono le regole a essidedicate nel nostro settore?Se non riusciamo a rispondere a queste domande … dispositivi e piattaforme del futuro ci prenderanno in contropiede.Dobbiamo iniziare … a separare del tutto contenuto e forma.La citazione è a effetto, ma quali sono i criteri che ci permettono di capire, se nella nostra azienda è giunto il momento diabbandonare la scrittura “free style”, ovvero la realizzazione manuale dei documenti, e avviare un progetto di gestionestrutturata dei contenuti utilizzati nel complesso della documentazione tecnica (manuali, guide rapide, help online,cataloghi, schede, listini, ecc.)?Analizzare i punti di debolezza della documentazione tecnica, i bisogni informativi dei destinatari, le normative, glistandard e le best practices di settore ci aiuta a rispondere a questa domanda, che rappresenta la prima tappa del nostroviaggio.I vincoli del “free style”Punti di debolezza della documentazione tecnica “free style”L’aumento della complessità della documentazione tecnica è il fattore che, più di ogni altro, evidenzia i limiti dellascrittura “free style”.Gestire i contenuti all’interno della pagina o della videata dei singoli documenti rende di per sé difficile: Far collaborare più figure professionali Aggiornare in modo certo contenuti presenti in piùdocumenti Garantire la coerenza dell’informazione, cioè – peresempio – il fatto che denominazione e descrizione dellamacchina corrispondano nella scheda tecnica allegataall’offerta e nella successiva fattura Standardizzare e riutilizzare i contenuti Utilizzare glossari e terminologie2Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 3. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.it Contenere i costi di traduzione, poiché le informazioni di partenza non sono standardizzate e univoche, né è agevoleindividuare e riutilizzare traduzioni già esistenti Omogeneizzare presentazione e formattazione dei contenuti Realizzare pubblicazioni multicanale (su carta, cd/dvd/usb, web, mobile, app, ecc.) e mirate a singoli destinatari(personale interno all’azienda, forza vendita, rivenditori e partner, installatori, utilizzatori, manutentori e assistenzatecnica, ecc.) Integrare i contenuti presenti nelle varie fonti dati aziendali (sistemi gestionali, software ERP, MRP, CAD, PDM,CMS, ecc.).Una semplice simulazione ci aiuta a capire come, all’aumento della complessità della documentazione tecnica, lascrittura “free style” finisca per rappresentare un fattore di inefficienza.Immaginiamo che in origine un’azienda tipo producesse 1 sola macchina, dedicata al mercato nazionale, per cui erasufficiente realizzare manualmente, con MS Word, 1 manuale in italiano.L’azienda ha poi iniziato a produrre la macchina in 6 modelli diversi. Ogni modifica a un contenuto comune ai manualiandava quindi replicata su 1 + 6 file di Word.Per ottemperare alla Direttiva Macchine, l’azienda ha scorporato il manuale per l’installatore / manutentore da quello perl’utilizzatore, creando 2 versioni per ogni manuale e ottenendo 1+6+12= 19 documenti di Word da manutenere.Per rispondere alle richieste degli utenti, l’azienda ha poi deciso di affiancare a ogni manuale una guida rapida, portandoa 1+6+12+12 = 31 1 documenti di Word.Infine, l’azienda ha iniziato a espandersi all’estero, il che ha richiesto la traduzione in 3 lingue di manuali e guide rapide.Il risultato è stato di 31 x 4 = 124 documenti di Word.La storia potrebbe continuare, includendo – per esempio – l’esigenza di pubblicare online la documentazione tecnica, dipersonalizzarla graficamente per i rivenditori primari, di realizzare cataloghi ricambi, ecc.: l’aggiunta di gradi dicomplessità farebbe aumentare inesorabilmente il numero di documenti di Word da manutenere, e con esso tempi, costie rischi di disallineamento.Compiendo un balzo in avanti, immaginiamo che l’azienda sia passata dalla scrittura “free style” alla gestione strutturatadei contenuti, adottando anche un software CMS (Content Management System).Standardizzazione, univocità e riutilizzo dei contenuti supportati dal software CMS fanno sì che ogni modifica a uncontenuto comune vada apportata in un solo punto (1 modifica nella prima lingua + 3 traduzioni) e sia poi propagata inautomatico a tutti i 124 documenti.L’efficienza è evidente, in termini di risparmio di tempi e costi, nonché di certezza del risultato.Bisogni informativi dei destinatari della comunicazione tecnicaOltre ai bisogni informativi primari, alcuni fattori – qualil’incremento della complessità dei macchinari, la contrazionedel tempo dedicato alla formazione, l’avvento del mobile,ovvero della possibilità di usufruire di contenuti in rete tramitedispositivi mobili (smartphone, tablet, ecc.) – fanno sorgerenuovi bisogni informativi nei destinatari della comunicazione.Fra i bisogni informativi primari annoveriamo l’esigenza didisporre di contenuti: Corretti, aggiornati e coerenti all’interno di tutti idocumenti che accompagnano il ciclo di vita della macchina(dalla proposta commerciale, all’installazione e formazionepresso il cliente, alla fatturazione, alla gestione dellaricambistica, ecc.) Di facile comprensione3Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 4. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.it Localizzati nella lingua del fruitore.I bisogni informativi emergenti sono invece rappresentati dall’esigenza di disporre di contenuti: Basati su immagini e video, per facilitare la comprensione della sequenza delle operazioni da svolgere Ricercabili Contestuali, cioè consultabili nel posto giusto e nel momento giusto, superando il gap attuale, per cui i contenuti sicollocano spesso altrove rispetto ai luoghi e ai tempi in cui sono effettivamente necessari Targetizzati per il profilo del fruitore, in modo tale da limitare il sovraccarico informativo Corredati da strumenti di condivisione di problemi e soluzioni Integrati e aggregati, in modo tale da non dover consultare separatamente più fonti per raccogliere i dati necessari.Dal momento che le informazioni sono parte integrante del prodotto, il fatto di rispondere non solo ai bisogni informativiprimari, ma anche a quelli emergenti, equivale a conferire un vantaggio competitivo al prodotto.Si tratta quindi di un tassello importante nella strategia aziendale. Un tassello, che implica la moltiplicazione dei canaliutilizzati e dei tipi di pubblicazione editi dall’azienda. Una moltiplicazione, che – come abbiamo visto in precedenza – lascrittura “free style”, a causa della sua manualità, non supporta in modo efficiente ed efficace.Attualmente il canale web e mobile è quello che catalizza la maggiore attenzione, poiché particolarmente adatto arealizzare e veicolare tipi di pubblicazione e funzioni in grado di rispondere ai bisogni informativi emergenti: Gallerie di immagini, video, modelli navigabili in 2D/3D, eventualmente collegati al catalogo ricambi Strumenti per la ricerca e il filtraggio delle informazioni Fornitura di informazioni contestuali, grazie a strumenti in grado di stabilire un collegamento fra l’ambiente reale incui opera l’utente e i contenuti disponibili. Per esempio, integrando lapposizione di codici QR (Quick Read) su partidella macchina con la realizzazione e la pubblicazione online di documentazione mirata, gli utenti possonoconsultare da dispositivi mobili informazioni contestuali: Istruzioni Indicazioni di parti di ricambio Avvisi (segnalazioni provenienti da knowledge base o forum; indicazione dei dispositivi di protezione individuali[DPI] da indossare, ecc.) FAQ, knowledge base, blog e forum per la collaborazione degli utenti fra loro e con l’azienda Applicazioni per la visualizzazione integrata e aggregata di contenuti, targetizzati in modo automatico in base alprofilo dell’utente.Nell’approccio “free style” la realizzazione di questo tipo di pubblicazioni e funzioni è estremamente onerosa, se nonimpossibile.Partendo invece da una gestione strutturata dei contenuti e da software CMS predisposti per alimentare in modoautomatico applicazioni web e mobile, la realizzazione di questo tipo di pubblicazioni e funzioni diventa una stradapercorribile agevolmente per aggiungere valore al patrimonio informativo aziendale, incrementandone la redditività, e perconferire al prodotto un vantaggio competitivo.Normativa, standard e best practicesNell’ambito della redazione di manuali e di istruzioni d’uso lanormativa di riferimento è vasta.Senza pretesa di completezza, le norme internazionali enazionali da considerare sono: Direttiva Macchine 2006/42/CE recepita a livellonazionale dal D. Lgs. 17/2010 Norme armonizzate 12100:2010 Sicurezza delmacchinario - Principi generali di progettazione - Valutazionedel rischio e riduzione del rischio: la norma regolamenta4Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 5. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.itanche le istruzioni duso e rinvia alla norma internazionale IEC 62079 recepita a livello europeo dalla norma EN62079, sostituita dalla IEC 82079-1:20129 ISO IEC 82079-1:2012 Preparation of instructions for use - Structuring, content and presentation - Part 1: Generalprinciples and detailed requirements UNI 10653:2003 "Qualità della documentazione tecnica di prodotto" UNI 10893:2000 "Documentazione tecnica di prodotto. Articolazione e ordine espositivo del contenuto" UNI/TS 11192:2006 "Documentazione tecnica di prodotto destinata allutente. Criteri per la classificazione".Alle normative si aggiungono poi: Standard di settore, come l’AECMA / ATA / S1000D per il settore aeronautico e militare Standard indipendenti, come il DITA (Darwin Information Typing Architecture) di OASIS (Organization for theAdvancement of Structured Information Standards) per le applicazioni di e-business Best practices della scrittura tecnica (technical writing).Norme, standard e best practices hanno l’obiettivo di migliorare la qualità dei contenuti, nonché dei processi diredazione, traduzione, pubblicazione e distribuzione della documentazione tecnica, regolando il flusso di lavoro, lastruttura, l’ordine espositivo e il contenuto delle informazioni, le regole semantiche della comunicazione, la presentazionegrafica, il formato dei file, ecc.Anche nella traduzione pratica di questi aspetti la scrittura “free style” fatica. Pensiamo solo a un contenutoapparentemente semplice come il warning. La normativa richiede, che ogni warning comprenda un pittogramma,l’etichetta relativa al tipo di warning (nota, attenzione, pericolo, divieto, ecc.), l’illustrazione della causa, delleconseguenze e dei rimedi. Gestendo a mano i contenuti, l’operatore deve ricordare e applicare la struttura prevista,impaginare il pittogramma e attribuire a ogni contenuto lo stile corretto.La gestione mediata da CMS permette invece di definire e applicare in automatico la struttura prevista, di aggiungere inautomatico il pittogramma e di esportare nei vari formati di file lo stesso contenuto, utilizzando in particolare tecnologieXML per trasformarlo nelle standard di destinazione(per esempio il DITA).Vantaggi della gestione strutturata dei contenuti e dell’adozione di CMSNella seconda tappa del nostro viaggio analizzeremo il modo in cui la gestione strutturata dei contenuti e l’adozione disoftware specifici (CMS, sistemi di editing, authoring tool, sistemi di impaginazione automatica, ecc.) possano aiutarci asuperare le debolezze della scrittura “free style”, a rispondere ai bisogni informativi dei destinatari, a recepire norme,standard e best practices, ovvero non solo a rendere efficiente la gestione dei contenuti, ma anche a incrementarne ilrendimento pubblicandoli e diffondendoli in modo efficace.Obiettivo è mettere a frutto il patrimonio informativo aziendale sia per migliorare il trasferimento della conoscenza deiprodotti e del loro utilizzo, sia per ampliare la gamma dei servizi di supporto offerti alla forza vendita, all’assistenzatecnica e agli utilizzatori.Le caratteristiche che prenderemo in esame si riferiscono ad Argo CMS, il software di KEA s.r.l. dedicato alla gestionecollaborativa di contenuti multilingua e alla produzione automatizzata di documentazione tecnica multicanale.Gestire i contenuti in modo strutturato, utilizzando un software CMS, comporta vantaggi così sintetizzabili:5Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 6. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.it Gestione collaborativa dei contenuti Grazie alla gestione delle autorizzazioni, il CMS permette a varie figure professionali, interne ed esterneall’azienda (product manager, technical writer, traduttori, consulenti, ecc.), di collaborare all’editing dei contenutiin base a flussi di lavoro codificati Gestione univoca dei contenuti riutilizzabili e delle loro revisioni Il CMS permette di gestire in modo univoco contenuti riutilizzabili a qualsiasi livello, dal macro al micro: capitoli,warning, termini tratti da glossari, variabili, ecc. Revisionando un contenuto comune, la modifica può essere o meno propagata in modo automatico alle sueistanze presenti nei vari documenti Supporto di glossari e terminologie Definizione e applicazione di strutture di contenuti (modelli, template) riutilizzabili, per esempio dei warning sopracitati Gestione delle traduzioni Attraverso un sistema di marcatura, il CMS permette di sottoporre al traduttore solo i contenuti da tradurre o darivedere, ottimizzando i costi Le traduzioni, eseguibili mediante software di traduzione assistita (CAT Tool, come SDL Trados, WordFast,ecc.), sono importate in modo automatico nel CMS. Ciò fa risparmiare tempo e garantisce la precisacorrispondenza fra testo originale e traduzione, svincolata dalle competenze linguistiche del technical writer Marcatura dei contenuti finalizzata al riutilizzo La marcatura o classificazione a faccette assegna "a un oggetto caratteristiche multiple (attributi), consentendodi ordinare e filtrare le informazioni da molteplici punti di vista, anziché in base a un unico schema predefinito,tassonomico. Una faccetta comprende attributi … chiaramente definiti, mutuamente esclusivi ecomplessivamente esaustivi. Per esempio un insieme di libri può essere classificato utilizzando una faccetta perlattributo Autore, una per lattributo Soggetto, una per lattributo Data, ecc." (Wikipedia). Attraverso la marcaturail technical writer definisce l’ambito di utilizzo di un contenuto comune, cioè – per esempio – a quale famiglia,modello, macchina, codice della distinta base (BOM – Bill of Material) si riferisce, qual è il suo destinatario, perquali tipi di pubblicazione è stato concepito, attraverso quali canali può essere veicolato, ecc. Sulla marcatura si basa, per esempio, il funzionamento dei configuratori della documentazione tecnica e laproduzione automatica di documenti targetizzati Automazione nella produzione dei vari tipi di documentazione tecnica, targetizzati per i vari destinatari, da veicolareattraverso i vari canali Grazie all’integrazione con software di impaginazione automatica e con applicazioni web, il CMS permette diautomatizzare le funzioni di cross media publishing. I vantaggi sono il risparmio di tempi e costi, la correttezzadei contenuti, la possibilità di targetizzare le informazioni, nonché la coerenza nell’applicazione degli stilemigrafici Il CMS permette anche di alimentare piattaforme di e-commerce, dedicate per esempio alla vendita di ricambi.Si tratta di un’opportunità interessante per trasformare in fonte di guadagno la gestione della documentazionetecnica, che in alcune realtà è ancora percepita soprattutto come fattore di costo Integrazione Il CMS spesso condivide dati (classificazioni, codici, prezzi, disegni, ecc.) con altri strumenti informatici presentiin azienda: sistemi gestionali, ERP, MRP, PLM, CAD, CMS web, ecc. Integrare il CMS nell’ecosistemainformativo è vantaggioso, poiché permette alle varie aree aziendali di condividere informazioni corrette, diutilizzarle per redigere i documenti che accompagnano ciclo di vita della macchina, nonché di fornireinformazioni aggregate, senza costringere gli utenti a consultare varie fonti per raccogliere i dati di cuinecessitano.6Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 7. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.itLa tecnologia da sola non bastaLa terza e ultima tappa del nostro viaggio si sofferma sullacentralità dell’opera di alfabetizzazione e formazione dellepersone, che – a vario titolo – sono chiamate a realizzare,gestire e utilizzare contenuti strutturati.Il successo del passaggio dalla scrittura “free style” allagestione strutturata dei contenuti dipende non soltanto dallescelte tecnologiche, ma anzitutto dalla comprensione,condivisione e applicazione di scelte metodologiche.Questo, perché l’obiettivo comune alle attività fin qui illustrateè di produrre contenuti "certificati", riutilizzabili allinterno delladocumentazione tecnica aziendale, comunicata a varidestinatari, attraverso vari canali e tipi di pubblicazione.Riutilizzare per migliorare la qualità della comunicazione eper incrementare il rendimento dellinvestimento necessarioalla produzione e traduzione delle informazioni.Nella nostra esperienza vi sono vari fattori metodologici, che concorrono al buon esito di un progetto di gestionestrutturata dei contenuti e di adozione di software CMS. Eccoli in dettaglio: Standardizzazione Standardizzare i contenuti significa esprimere in modo uguale concetti uguali. In fase di migrazione deicontenuti verso software CMS la standardizzazione è fondamentale, poiché permette di scrivere e tradurre unasola volta un’informazione, migliorando lefficienza della redazione (editing) e della traduzione, e rendendocoerente la comunicazione La standardizzazione include anche l’applicazione di regole e standard della scrittura tecnica (technical writing) Univocità Per rendere efficienti redazione e traduzione, ogni contenuto deve essere univoco: va gestito cioè una solavolta nel sistema e riutilizzato laddove necessario. Nel software CMS ogni frammento di contenuto (snippet)segue il proprio ciclo di vita e può essere presente in una o più revisioni, ognuna delle quali utilizzata in una opiù pubblicazioni. Lunivocità è la chiave per modificare l’informazione in un solo punto e propagare in modocerto la modifica a tutte le istanze Granularità Un punto di forza dei sistemi di gestione dei contenuti sta nella loro capacità di agevolare il riutilizzo delleinformazioni. Per riutilizzare un contenuto è necessario, che esso sia disponibile a un livello di granularitàadeguato. Per esempio: Se il capitolo di presentazione della tavola dei pittogrammi va sempre riutilizzato in toto, può essere gestitoa un basso livello di granularità, cioè come un unico blocco, composto da una serie di paragrafi, chesaranno riutilizzati sempre tutti insieme Nel caso dei warning, che vanno utilizzati singolarmente, è invece necessario granularizzare maggiormentei contenuti Il massimo grado di granularizzazione va riservato infine a termini del glossario e a dati variabili(denominazioni di famiglia, modello o macchina, codice matricola, ecc.), che sono inseriti in-line, cioè nelflusso del testo di paragrafi presenti in uno o più documenti Classificazione e marcatura Per riutilizzare i contenuti è necessario che il technical writer riesca a trovare facilmente linformazione cercata ea comprendere in quale ambito un determinato contenuto possa essere utilizzato. Sono fondamentali in questosenso un sistema di classificazione condiviso e funzioni di filtraggio delle informazioni basate sulle marcatureapportate.7Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS
  • 8. Kea s.r.l. | Via Strà, 102 | 37042 Caldiero (VR)Tel. / Fax: +39 045 6152381Web: www.keanet.it | E-mail: info@keanet.itConclusioneSe ci sono aspetti in cui vi riconoscete e pensate possa essere opportuno ipotizzare l’avvio diun progetto di gestione strutturata dei contenuti, siamo a vostra disposizione per un’analisigratuita della documentazione tecnica e dei vostri flussi di lavoro attuali, e per provare dalvivo il nostro software Argo CMS.Contattateci a info@keanet.it o al numero di telefono +39 045 6152381!Autore: Petra Dal SantoPetra Dal Santo è fondatrice e socia di KEA s.r.l., dove si occupa di project management nell’ambitodi progetti legati all’adozione di software CMS, all’impaginazione automatica, nonché allo sviluppo di applicazioni web emobile. E’ autrice del blog di KEA, dedicato ai temi della comunicazione e documentazione tecnica.E-mail: dalsanto@keanet.itSito: http://www.keanet.itBlog: http://blog.keanet.it/8Perché passare dalla scrittura “free style” alla gestione strutturata dei contenuti, adottando software CMS