sabato 9 novembre 2019

Minimalismo: mettiamo in ordine le idee

Vi segnalo questo articolo in cui Ferry Vermeulen intervista il Prof. Hans van der Meij, considerato il maggior esperto del Minimalismo.
E' un'occasione da non perdere, per due motivi:

  • Non capita spesso di poter accedere "direttamente" alla sorgente della conoscenza di un determinato argomento.
  • Sul Minimalismo c'è da sempre molta confusione... conviene chiarirsi le idee.
Il Minimalismo è una filosofia per la redazione dei contenuti che si basa su 4 principi:

  1. Orientato all’azione.
  2. Associazione tra lo strumento e il compito da eseguire. 
  3. Supporto al riconoscimento e alla risoluzione degli errori.
  4. Fornire all’utente le informazioni essenziali e lasciarlo libero di scoprire i dettagli in autonomia.

I primi due principi significano "orientati al processo" (Task Oriented)
Il terzo significa "risoluzione dei problemi" (Troubleshooting)
Il quarto significa "sintesi sul contesto" (Context Oriented)

Tutto semplice vero? Parrebbe di no.

Nell'ultima versione dello standard IEC IEEE 82079-1, al paragrafo 5.5.3 viene fornita una definizione di Minimalismo... vagamente imprecisa:

Minimalism is an approach to information for use that includes
critical information and the least amount of other information needed to be complete. Critical information includes the safe use of the product, the security of the information created with the product, or the privacy of the information created by or stored with the product.

Questa NON E' LA DEFINIZIONE DI MINIMALISMO... e credo che su questo punto ci siano pochi dubbi.

Il MInimalismo, peraltro, ha ispirato anche alcune caratteristiche di DITA, lo standard più diffuso al mondo per l'ingegnerizzazione dei contenuti.

Ad esempio, nella versione 1.3 di DITA, è stato introdotto il Troubleshooting Topic Type, che va a mappare proprio il principio n°3.

Quindi, andate sul sito di Ferry e seguite le risposte del Prof. Hans van der Meij.
A presto.


Leggi questo articolo...

martedì 3 settembre 2019

Un brevetto per la sincronizzazione dei contenuti

Da qualche tempo è disponibile su Google Patent il brevetto che ho ideato nelle prime settimane del 2015, mentre lavoravo in IBM:

ON DEMAND SYNCHRONIZATION OF INFORMATION
(Sincronizzazione delle informazioni su richiesta)

Di che si tratta? Di un'idea finalizzata a risolvere un problema classico delle grandi (ma anche delle piccole) organizzazioni: la proliferazione di silos di contenuti completamente scorrelati e disallineati.

Sul tema sono stati scritti fiumi d'inchiostro, spesso invano, nonostante le migliori intenzioni di alcuni manager aziendali "illuminati" e la disponibilità di tecnologie e best practice adatte allo scopo.

A questo punto, è necessario un breve flash-back.

Arrivato in IBM nel ruolo di Documentation Manager di CrossIdeas, ed essendo quindi il massimo esperto della documentazione della piattaforma IDEAS, nei primi mesi di lavoro venni contattato da diversi colleghi di altre aree (training, marketing, integration, etc) che sviluppavano contenuti inerenti al prodotto.

Di fatto, vidi in presa diretta lo sviluppo di diversi "silos" di contenuti.



Inizialmente, tali silos erano legati alla "radice" della documentazione tecnica di prodotto.
Ma in seguito e per tutta una serie di ovvie ragioni, queste aree tendevano a procedere con un certo grado di autonomia, costituendo silos informativi potenzialmente disallineati.

Mi resi conto che questa dinamica implicava un problema: nel momento in cui apportavo una modifica "significativa" alla doc di prodotto (sorgente), questa modifica doveva essere comunicata a tutti i referenti interessati.

Non sarebbe stato opportuno instaurare un "automatismo" per tenere allineati i diversi silos?

Da questa banale osservazione, ideai una generalizzazione della soluzione dell'allineamento dei silos (ATTENZIONE! NON DELL'ELIMINAZIONE DEI SILOS... cosa che ritengo impossibile, specialmente nelle grandi organizzazioni... ma questa è un'altra conversazione).

L'idea è semplice:

  1. Un UTILIZZATORE di contenuti elegge una SORGENTE AFFIDABILE di contenuti e instaura un CONTRATTO con la sorgente.
  2. L'utilizzatore può includere nei suoi documenti dei contenuti pubblicati dalla sorgente.
  3. Quando un contenuto della sorgente cambia, l'utilizzatore ha la possibilità (mai l'obbligo) di aggiornare AUTOMATICAMENTE la variazione.
  4. In questo modo, i documenti dell'utilizzatore sono sempre allineabili con la sorgente.


UN ESEMPIO SEMPLICE

Immaginate di utilizzare delle tabelle della FAO in una presentazione.
Le tabelle, nel tempo, cambiano. Se volete essere certi di utilizzare sempre la tabella più recente, magari dovete andare ogni tanto sul sito della FAO e verificare eventuali variazioni.
Se la tabella è cambiata, dovete decidere se prendere la nuova tabella e aggiornare la presentazione oppure no.

Il paradigma è "L'UTENTE CHE CERCA L'INFORMAZIONE"... ricordate?
Questo paradigma è SEMPLICEMENTE il paradigma SBAGLIATO!

Non sarebbe meglio avere un meccanismo che, al variare della tabella, trasferisce automaticamente la tabella aggiornata nella mia presentazione? Cioè "L'INFORMAZIONE CHE CERCA L'UTENTE"... il paradigma giusto!

Ora allarghiamo il campo di gioco.

Immaginate di avere N documenti che attingono da K sorgenti (di solito con N>K). Ora, al variare dei contenuti di K sorgenti, dovete andare periodicamente a verificare se non sia necessario aggiornare "a mano" gli N documenti.

In questo gioco, voi perdete sempre e perdete tanto più velocemente quanto più alti sono i valori di N e K.

Se invece avete K contratti con le K sorgenti, potete allineare gli N documenti in modo quasi indolore. Ora non entro nei dettagli tecnici del meccanismo (content tagging, notifica della variazione, accettazione, etc), che potete approfondire leggendo il brevetto.

Si pone una sola ipotesi: la sorgente espone contenuti attraverso un linguaggio taggato (XML, HTML, etc).

La bontà del brevetto consiste nel non fare nessuna assunzione specifica sul:

  • tipo della sorgente
  • numero di sorgenti
  • contenuti della sorgente
  • tipo/formato di documenti collegati alla sorgente

Per la precisione, il brevetto è stato realizzato grazie alla preziosa collaborazione di altri 4 colleghi:
Cristina Bonanni, Patrizia Manganelli, Andrea Durastante e Andrea Di Maio.
Devo sottolineare il fondamentale apporto di Cristina e Patriza, perchè io ero al primo brevetto mentre loro avevano già alle spalle diversi brevetti e la loro esperienza è stata decisiva nella formalizzazione di questa intuizione.

Il brevetto è attualmente di proprietà della IBM, a cui abbiamo ceduto tutti i diritti.

Se l'argomento vi interessa e volete approfondirlo mi potete contattare.

Ciao. Leggi questo articolo...

mercoledì 22 maggio 2019

Breve guida al nuovo standard IEC / IEEE 82079-1: 2019

Il 16/5/2019 è’ stato pubblicato lo standard IEC / IEEE 82079-1: 2019 che sostituisce la prima edizione, IEC 82079-1: 2012

Lo standard fornisce i principi generali per la progettazione e la formulazione delle istruzioni per l'uso di prodotti di tutti i tipi, da un frigorifero domestico, ad un software o a prodotti di grandi dimensioni o molto complessi, come un trattore o grandi macchinari industriali.

Questa edizione, rispetto alla precedente, include notevoli modifiche.

NUOVA STRUTTURA
Una  riorganizzazione della struttura del documento, per facilitare l'applicazione dello standard e la ricerca di informazioni.

INFORMAZIONI PER L'USO... e non documentazione
Le informazioni per l'uso sono introdotte come termine generico.
Le istruzioni per l'uso sono sinonimo di informazioni per l'uso.
Questo approccio riflette una tendenza che si orienta nel rimuovere il termine “documentazione” che tradizionalmente richiama l’idea di una forma documentale cartacea. Oggi le informazioni per l’uso necessarie ad utilizzare un prodotto possono assumere diversi formati digitali (oltre al sempre possibile formato cartaceo) e quindi il termine “informazioni per l’uso” risulta molto più flessibile.

PRINCIPI
Il Capitolo 5 si concentra sullo scopo delle informazioni per l'uso, sulla qualità e sul processo di gestione delle informazioni.

GESTIONE
Il Capitolo 6 definisce gli elementi principali del processo di gestione delle informazioni per l'uso. Vengono forniti i criteri di riferimento per la definizione del “processo redazionale” , innervata da alcuni elementi di project management, risk management, quality assurance e test dei contenuti.

CONTENUTI
Il Capitolo 7 entra nel dettaglio di cosa deve essere contenuto nelle informazioni per l’uso.
Tra i molti aspetti trattati, mi preme orientarvi sul paragrafo 7.11, che parla degli aspetti relativi alla sicurezza e di come le tematiche di sicurezza devono essere gestite nella definizione delle informazioni per l’uso “sicuro” di un prodotto.

STRUTTURA
Il Capitolo 8 parla della struttura delle informazioni per l’uso.
In particolare, nel paragrafo 8.2 si delinea la distinzione tra tre tipi di informazioni:

  • concept
  • task
  • reference

Quindi, chi adotta uno standard come DITA, automaticamente si ritrova ad essere conforme con questa area dello standard.
Inoltre, nel paragrafo 8.4.3.2 si indica il concetto di “context sensitivity” (riferita in particolare alle informazioni per l’uso fruite attraverso dispositivi digitali).
Ne riparleremo presto, perché su questo concetto si basa il futuro della Comunicazione Tecnica: context-based e user-based, ma definita dinamicamente e non pre-determinata (se non nelle componenti molecolari).

FORMATO
Nel Capitolo 9 si fa riferimento ai diversi formati con i quali possono essere distribuite le informazioni per l'uso.

CHECK-LIST DI CONFORMITA'
Infine, tra gli allegati, una check-list per verificare se le vostre informazioni per l’uso sono conformi allo standard.

Questo standard deve essere noto a tutti coloro che sono coinvolti nella concettualizzazione, creazione, manutenzione, traduzione, localizzazione, integrazione di contenuti, produzione, e valutazione delle informazioni per l'uso associate ad un prodotto.

Infine, voglio sottolineare come questo deve essere inteso come uno standard “orizzontale”, che si propone come lo standard di riferimento per la redazione di qualsiasi tipo di informazione per l’uso, per qualsiasi prodotto.

Se volete prendere in visione un estratto ridotto dello standard, compreso l’indice dei contenuti, potete accedere a questo link.

Leggi questo articolo...

venerdì 15 febbraio 2019

L'Artigiano di Babele compie 10 anni


10 anni di blog!

E chi se lo aspettava?

All'inizio è stata una scommessa al buio.

Poi si è trasformato in una "palestra" dove ho trovato stimoli e idee per crescere ed affinare "i muscoli della scrittura".

Poi è diventato anche un "salotto" dove mi è capitato di incontrare tanti colleghi e appassionati della scrittura tecnica.

Ma anche un "laboratorio", dove proporre tante diverse chiavi di lettura sulle tematiche professionali che ho affrontato.

Circa 343.000 visite in 10 anni, poco più di 34.000 all'anno, quasi 3.000 al mese, circa 100 al giorno, tutti i giorni, per 10 anni!

Un percorso partito da qui e tanti passaggi chiave, con alcuni momenti di svolta, come questo, oppure questo.

E poi tanto altro ancora.

Nel 2009 mi sentivo un artigiano, alla continua ricerca di strumenti, metodi e processi che mi hanno progressivamente portato all'essenza della Comunicazione Tecnica, che si basa "sull'ingegneria dei contenuti" (bellissima espressione del mio amico Antonio Murro).

341 articoli (e con questo 342), ognuno dei quali rappresenta un passaggio di crescita, lo snodo di un ragionamento, una proposta di confronto rivolta a tutti i miei lettori, alla luce del sole.

Ma stasera non ho voglia di stilare troppe statistiche, fare grafici e analisi, recuperare indicazioni nascoste nei dati.

Voglio solo voltarmi indietro per vedere quanta strada ho percorso con questo compagno di viaggio, il mio blog, in attesa di tutta la strada futura ancora da fare.


A presto!
:-)



Leggi questo articolo...

sabato 9 febbraio 2019

Revisione della Direttiva Macchine: quali sono gli orientamenti?

Oggi vi segnalo un contenuto molto interessante, presente sul sito della Commissione Europea, nell'area del Diritto e precisamente per quanto inerente al processo di revisione della Direttiva Macchine.

In questa sezione sono elencati, attualmente, 72 pareri di varie organizzazioni professionali europee in merito:

  • alla necessità di revisionare la Direttiva Macchine
  • ai principali aspetti da tenere in considerazione nella eventuale attività di revisione

Fra questi pareri, potete leggere anche la posizione della European Association for Technical Communication - tekom Europe.

Lo scorso anno è stato elaborato un Position Paper che chiariva l'orientamento della tekom Europe sull'argomento e metteva in risalto alcune aree strategiche, tra cui l'annosa questione di poter fornire agli utenti le istruzioni per l'uso del prodotto in formato digitale.

Con questo parere si ribadisce il punto e si sottolinea anche il ruolo delle autorità di sorveglianza nel far rispettare l'applicazione degli standard.

E' interessante anche fare una panoramica dei diversi pareri di altre organizzazioni, per farsi un'idea di come potrebbe orientarsi la Commissione Europea in merito alla necessità di operare una revisione della Direttiva.

Il mio parere è ben noto.

Io ritengo che la Direttiva Macchine fosse già datata nel momento in cui è stata pubblicata e nell'ambito dell'Advisory Board for Standard and Legislation della tekom Europe ho tentato di dare un piccolo contributo nella direzione dell'innovazione.

Personalmente, credo che si dovrà poi fare sempre più attenzione al problema della cyber-security,  un aspetto che diverrà cruciale nei prossimi anni, in cui avremo macchine sempre più "intelligenti e connesse" in ecosistemi IoT based.

Uno dei maggiori meriti della Direttiva Macchine è proprio quello di sottolineare gli aspetti relativi alla sicurezza nell'uso delle macchine e immaginate cosa potrebbe accadere, nel futuro, se un hacker potesse prendere il controllo di macchine cooperanti in un qualsiasi sistema di produzione o di trasporto o medicale o... fate voi!

Leggendo i diversi pareri emerge questo aspetto anche nelle riflessioni di altre organizzazioni.

Vediamo ora come evolverà la situazione.
A presto!


Leggi questo articolo...

giovedì 24 gennaio 2019

Nuova versione dello standard ISO/IEC/IEEE 26515: Agile User Information

Stasera vi segnalo un articolo che ho scritto insieme a Sissi Closs ed Andrea Gocke, pubblicato sul sito della tekom Europe.

L'articolo illustra i tratti salienti del nuovo standard ISO/IEC/IEEE 26515, pubblicato a Dicembre del 2018.

Lo standard suggerisce le best practice per gestire lo sviluppo delle informazioni per gli utenti nell'ambito di organizzazioni che adottano processi di sviluppo Agile.

Come alcuni di voi sanno, faccio parte dell'Advisory Board for Standard and Legislation della tekom Europe e, tra le altre cose, ho collaborato molto attivamente alla revisione di questo standard.

Vi rimando alla lettura dell'articolo per i dettagli, ma qui voglio elencare brevemente alcuni elementi fondamentali che possono esservi utile per capire l'effettivo valore di questo standard dal punto di vista di un Comunicatore Tecnico.


INFORMAZIONI PER GLI UTENTI, NON DOCUMENTAZIONE

La classica prospettiva della documentazione orientata al "manuale", quindi una struttura gerarchico-sequenziale, è morta.

Le informazioni per gli utenti oggi sono "ingegnerizzate" a partire da un set di elementi riutilizzabili in una logica multi-canale e multi-formato.

Quindi parliamo di "user-assistance", di informazioni che possono essere fruite da sistemi multimediali che utilizzano animazione, video e audio, realtà aumentata, interfacce software: è "l'informazione intelligente", parametrizzabile in base al contesto, agli eventi, al profilo dell'utilizzatore... e ad altri criteri.

Il vecchio manuale cartaceo c'è ancora, ma sempre più sullo sfondo e marginale.

Per questo motivo abbiamo deciso di usare un concetto più ampio: informazioni per gli utenti.


AGILE = NESSUNA DOCUMENTAZIONE? FALSO!

Molte aziende in tutto il mondo utilizzano processi agili per sviluppare i loro prodotti.

Lo sviluppo agile si basa su un insieme di principi e metodologie basate sui principi descritti nel Manifesto Agile pubblicato nel 2001.

Sviluppo iterativo ed evoluzione dei requisiti, attraverso la collaborazione tra team cross-funzionali e auto-organizzanti, per  produrre, ad ogni iterazione, funzionalità pronte per essere utilizzate dal cliente. Al termine di ogni iterazione, analisi di quanto prodotto e feedback dei clienti per migliorare la prossima iterazione.

In questa dinamica, viene quasi azzerata del tutta la "documentazione interna" associata al processo di sviluppo del prodotto.

Ma rimane intatta la necessità di produrre le informazioni per l'utente che dovrà usare il prodotto!


IL RUOLO DEL COMUNICATORE TECNICO VIENE VALORIZZATO

Questo standard promuove anche un ruolo più centrale dei Comunicatori Tecnici nella catena dello sviluppo di valore del prodotto, lungo tutto il ciclo di vita del prodotto.

In Agile non si dispone di documentazione dettagliata a supporto dello sviluppo del prodotto. Un'iterazione dura soltanto 2-4 settimane, non ci sono tempi morti.

Il Comunicatore Tecnico deve far parte del team di sviluppo, stare gomito a gomito con gli ideatori e sviluppatori del prodotto, diventare in una certa misura "esperto del prodotto".

Altrimenti non può scrivere informazioni per gli utenti a cui è destinato il prodotto!

Un esempio? Trovatemi un collega che documenta delle API dentro una logica di processo Agile e che non sia in grado anche di leggere e capire, almeno a grandi linee, il codice (JAVA, C++, etc.) che deve documentare.

Non perdete tempo... non lo troverete mai!

Questo e molto altro troverete in questo standard.

Prossimamente, scriverò qualche articolo per dettagliare alcune questioni che ritengo rilevanti.

Intanto, qui potete acquistare lo standard.

A presto!

Leggi questo articolo...