Leggi questo articolo...
Il prossimo 3 Marzo sarò ospite dell'Università Rennes 2.
Nell'ambito del Master's degree in Technical Communication, Project Management, Terminology and Translation, illustrerò agli studenti le caratteristiche della nuova versione dello standard ISO/IEEE/IEC 26514:2022, che è stato recentemente rilasciato nel mese di Gennaio.
Sono contento di aver dato il mio contributo all'innovazione di questo standard, sia come rappresentate UNI per l'Italia in seno alla JTC 1/SC 7/WG 2 Committee, sia come membro dell'ABLS della tekom EUROPE.
Ringrazio Katell Hernandez Morin e Nolwenn Kerzreho per l'invito, in un luogo dove tanti altri illustri colleghi hanno offerto il loro contributo sulle tematiche più avanzate della Comunicazione Tecnica.
E ringrazio la mia azienda PTV SISTeMA (PTV Group) per il supporto.
Lo standard 26514 fa parte del gruppo degli standars ISO 265XX, che identificano le best practice nella produzione delle informazoni per l'uso dei prodotti software e nella definizione e gestione di tutti i processi associati.
Per me sarà una bella esperienza, e spero anche per gli studenti!
Leggi questo articolo...Come vi avevo preannunciato alla fine di Novembre, è ora disponibile la nuova versione dello standard ISO/IEC/IEEE 26514:2022.
Tale standard è il principale standard di riferimento per la produzione delle informazioni per l'uso di un prodotto software.
Una prima osservazione: come nello standard ISO 82079, che è lo standard orizzontale di riferimento per qualsiasi tipo di prodotto (e quindi anche per i prodotti software), anche qui scompare il concetto di "documentazione/documento/manuale" ma si parla di "informazioni per l'uso/per gli utenti".
Può sembrare una banalità formale, in realtà è una conquista concettuale ottenuta dopo anni di dibattito: non esistono più i "documenti" o i "manuali", cioè i "contenitori" in cui vengono organizzate le informazioni, ma esistono fondamentalmente "le informazioni".
Il focus deve essere sulle "informazioni" ed eventualmente sui meta-dati che sono associati alle informazioni; le informazioni devono essere "modulari", di granularità abbastanza fine, devono essere i nostri "mattoncini Lego" che possiamo profilare e assemblare nei modi più opportuni in diversi contenitori, che sono ciò che chiamiamo "documenti".
Ma i documenti sono solo l'output di un processo.
Spesso tali contenitori non assumono più nemmeno una forma cartacea, ma rimangono prevalentemente in forma digitale.
Come sapete, anche il nuovo Regolamento Macchine (ancora in via di definizione) si sta orientando in tal senso, dando finalmente più spazio e libertà alla definizione delle informazioni in formato elettronico/digitale.
Ma ritorniamo allo standard 26514.
Il nuovo standard è organizzato in 64 pagine, meno della metà della versione precedente (2008, 143 pagine).
Sono state eliminate molte inutili sovrapposizioni con altri standard che nel frattempo si sono evoluti e consolidati, facendo esplicito riferimento a tali standard quando un argomento, presente nella vecchia versione 26514:2008, era meglio delineato nello standard specifico.
Molti i riferimenti allo standard 82079 ma anche agli altri standard del blocco 265xx; attraverso tali riferimenti è stato possibile "tagliare" le parti ridondanti e che potevano creare fraintendimenti.
Lo standard è sostanzialmente suddiviso in due parti.
PRIMA PARTE - Gestione del processo di sviluppo delle informazioni (Cap. 5 e 6)
Qui ci sono tutti gli aspetti di Project Management e Information Architecture applicate allo sviluppo delle informazioni. In particolare, il Cap. 6 può essere preso come punto di riferimento per la gestione del "processo redazionale" che può essere applicabile a TUTTI I TIPI DI PRODOTTO, quindi non solo ai prodotti software.
Nella precedente versione questi concetti erano diluiti in 5 capitoli (5,6,7,8,9), rendendo oggettivamente un poco troppo pesante lo sviluppo dell'argomento.
ATTENZIONE per tutti coloro che, specialmente negli ultimi due anni di pandemia, hanno scoperto la necessità di DIGITALIZZARE I PROCESSI AZIENDALI... perché non sarete mai in grado di digitalizzare nessun processo se prima non digitalizzate i vostri contenuti!
E per digitalizzare i contenuti avete bisogno di un'Architettura delle Informazioni.
Il Cap. 6 di questo standard vi fornisce le linee guida per indirizzare questo lavoro. I principi espressi si possono usare non solo per la gestione delle informazioni di uno specifico prodotto software ma, ad esempio, anche nel caso in cui vogliate strutturare una Knowledge Base aziendale.
SECONDA PARTE - Definizione delle informazioni (Cap. 7, 8, 9)
Qui trovate molte novità.
Il Cap 7. fornisce le linee guida per definire la Qualità delle informazioni; nel precedente standard questi concetti erano citati e spezzettati in diversi capitoli, ma qui è stato fatto uno sforzo di sintesi per fornire i riferimenti essenziali di base su un argomento rispetto al quale si dibatte da almeno 30 anni.
Nel Cap. 8 trovate le linee guida sulla strutturazione delle informazioni.
Inoltre trovate alcuni nuovi contenuti, completamente assenti nella versione precedente.
Ad esempio, come definire le informazioni relative alle API (vi ho già parlato dell'importanza delle API nelle moderne architetture software, presto ritorneremo a parlarne), o l'analogo per quanto riguarda i Chatbot.
Nel Cap. 9 un'estesa trattazione sui formati che potete definire per confezionare le informazioni.
Poi ci sono 2 appendici, relative agli aspetti generali più propriamente linguistici e di traduzione delle informazioni per l'uso. Ovviamente non si entra nel dettaglio perché ci sono altri standard su questi argomenti, ma si forniscono alcuni principi generali che non bisogna mai dimenticare.
A mio parere è stato fatto un gran lavoro, che si è sviluppato nell'arco di circa 30 mesi.
Sono contento di aver dato il mio contributo all'innovazione di questo standard, sia come rappresentate per l'Italia in seno alla JTC 1/SC 7/WG 2 Committee, sia come membro dell'ABLS della tekom EUROPE.
A presto!
E' in via di pubblicazione la nuova versione dello standard ISO/IEC/IEEE 26514.
Probabilmente sarà disponibile nei primi giorni di Gennaio 2022, dopo un processo di revisione partito nel Luglio del 2019.
26514 è lo standard per i progettisti e gli sviluppatori delle informazioni per gli utenti che accompagnano un prodotto software.
Erroneamente si potrebbe pensare che sia applicabile solo ai prodotti software. In realtà, la gran parte dei concetti esposti si può applicare anche alla gestione dei processi di documentazione di un qualsiasi prodotto.
Lo standard descrive principalmente:
In data 21 aprile 2021 è stata pubblicata la bozza della proposta del nuovo Regolamento Macchine che andrà a sostituire l’attuale Direttiva Macchine 2006/42/CE.
La prima grande novità è la scelta di passare da una Direttiva ad un Regolamento.
Una Direttiva richiede il recepimento del legislatore nazionale, cioè richiede una legge nazionale che renda esecutiva la Direttiva Europea. Un Regolamento è un atto legislativo dell’Unione Europea DIRETTAMENTE applicabile in ciascuno degli Stati membri.
Questo nuovo Regolamento nasce per:
Nel seguito un breve elenco degli aspetti salienti, con qualche considerazione di scenario, lasciando i maggiori dettagli ad una lettura necessariamente più approfondita della bozza (55 pagine).
APPLICAZIONE DEL NUOVO REGOLAMENTO MACCHINE
Il Regolamento Macchine entrerà in vigore il ventesimo giorno dopo la sua pubblicazione e verrà applicato dopo ulteriori 30 mesi. Ad oggi, si può cautamente ipotizzare che l'iter di pubblicazione del Regolamento possa essere completato entro il primo trimestre del 2022.
L’attuale Direttiva 2006/42/CE sarà abrogata nel momento in cui entrerà in vigore il Regolamento, ma sarà ancora possibile immettere sul mercato macchine conformi alla Direttiva per ulteriori 42 mesi dopo la data di entrata in vigore del Regolamento.
Le violazioni del Regolamento sono soggette a sanzioni stabilite dagli Stati membri, in base a criteri che dovranno essere comunicati alla Commissione entro 24 mesi dall’entrata in vigore del nuovo Regolamento.
OPERATORI ECONOMICI: IMPORTATORE E DISTRIBUTORE
Oltre al COSTRUTTORE, figura già delineata nella Direttiva, entrano in gioco l'IMPORTATORE e il DISTRIBUTORE.
L’IMPORTATORE è il soggetto che immette sul mercato UE un prodotto proveniente da un paese terzo. Deve assicurarsi che il fabbricante abbia completato le procedure per la valutazione della conformità del prodotto e deve specificare sul prodotto i propri dati identificativi; quindi, l’importatore diventa responsabile della conformità del prodotto e ne risponde in prima persona.
L'introduzione di questo profilo di responsabilità avrà, probabilmente, un impatto anche sulla qualità della documentazione tecnica che accompagna il prodotto e che deve essere conservata per 10 anni.
Il DISTRIBUTORE è un soggetto, distinto dal fabbricante o dall’importatore, che provvede a mettere il prodotto sul mercato. Il suo profilo di responsabilità è meno accentuato, ma deve verificare:
DOCUMENTAZIONE DEL PRODOTTO
Altra novità: la documentazione che accompagna il prodotto potrà essere fornita in formato digitale, ad esempio rendendola disponibile su un sito web o su un supporto ad-hoc, ad esempio un USB Key. L’utilizzatore potrà però richiedere, al momento dell’acquisto, una copia cartacea che dovrà essere fornita gratuitamente.
Su questo punto, molte organizzazioni hanno stimolato la Commissione Europea.
L'Advisory Board for Legislation and Standards della tekom Europe, di cui faccio parte, ha espresso il suo orientamento nella direzione di una necessaria revisione della vecchia Direttiva, prevalentemente nell'ambito dei criteri per la produzione della documentazione che accompagna il prodotto.
La tekom Europe, congiuntamente con altre organizzazioni, ha presentato un Position Paper ufficiale, focalizzato proprio sulle istruzioni per l'uso in formato elettronico.
COMPONENTI DI SICUREZZA
Altra notevole novità: nella definizione di “componente di sicurezza” del nuovo Regolamento, sono stati introdotti anche i componenti digitali, compreso il software. Il software che svolge funzioni di sicurezza dovrà essere marcato CE ed essere accompagnato da una dichiarazione di conformità UE.
DICHIARAZIONE CONFORMITA' UE
La dichiarazione CE di conformità è stata sostituita da una dichiarazione di conformità UE, in linea con il nuovo quadro legislativo. Quando ad un prodotto si applicano più atti dell’UE, deve essere redatta un’unica dichiarazione di conformità UE che li racchiude tutti.
CYBERSECURITY
Altra importante novità: si prende atto che oggi le macchine (e sempre pù nei prossimi anni) sono sempre più interconnesse in rete, strutturate in sistemi potenzialmente molto complessi ed esposte ad attacchi del tutto analoghi a quelli che vengono effettuati contro le reti di computer. Sono già stati documentatti eventi di questo tipo e sono destinati ad aumentare in futuro.
Il nuovo Regolamento Macchine prescrive che i circuiti di comando che svolgono funzioni di sicurezza siano progettati in modo da evitare attacchi che possano causare comportamenti pericolosi delle macchine.
La conseguenza logica di questa indicazione ci fa immaginare che in futuro avremo macchine protette da strati software specifici, come anti-virus, firewall, intrusion detectors o machine learning engine, del tutto simili a quelli che usiamo per proteggere le reti di computer.
Ovviamente questi aspetti avranno un impatto sul documento di valutazione dei rischi, che deve accompagnare la macchina.
STRESS PSICOLOGICO
Ambienti di lavoro robotizzati, in cui operatori umani condividono spazi di lavoro e processi con macchine robotizzate sempre più efficienti, possono generare dinamiche di stress per l'operatore umano. Tali elementi devono essere valutati per rispondere al requisito essenziale di sicurezza e di tutela della salute del lavoratore.
ALLEGATO IV della Direttiva diventa ALLEGATO I nel Regolamento
L’ALLEGATO IV della Direttiva, contenente la lista dei prodotti ad alto rischio, diviene ALLEGATO I del nuovo Regolamento. Ai prodotti compresi in questo allegato sono stati aggiunti i software e i sistemi di intelligenza artificiale che svolgono funzioni di sicurezza. Per questi prodotti, non è prevista la possibilità per il fabbricante di applicare la procedura di valutazione della conformità con controllo interno; quindi sarà sempre necessario l’intervento di un organismo "esterno".
ENTI NOTIFICATI
Gli Stati membri dovranno provvedere alla creazione e alla supervisione di enti notificati, incaricati dello svolgimento del risk-assessment sui macchinari e le loro funzionalità. Tali enti e le autorità che gestiscono le informazioni relative ai macchinari e ai soggetti produttori, importatori e distributori devono garantire la riservatezza dei dati contenuti nella documentazione che viene loro fornita.
Questo è uno degli aspetti più controversi del nuovo Regolamento Macchine.
Alcuni temono che l'attività di risk-assessment affidata ad una terza parte, per tutti i macchinari ad alto rischio, possa aumentare i costi di produzione e accrescere oneri amministrativi e tempi di commercializzazione.
Del resto, nell'esperienza professionale di molti miei colleghi che si occupano della documentazione tecnica delle macchine, ci sono innumerevoli episodi di macchine spesso carenti nella valutazione dei rischi o nella progettazione di base delle soluzioni di sicurezza.
La cronaca, anche recente, poi ci conferma come spesso le macchine vengano utilizzate rimuovendo i ripari di sicurezza o disattivando altri sistemi di sicurezza previsti, come nel caso della tragedia della funivia del Mottarone.
QUALI CONCLUSIONI POSSIAMO TRARRE?
Premesso che la bozza pubblicata potrebbe essere modificata e che i molti attori in campo non sono tutti concordi rispetto alle diverse modifiche introdotte rispetto alla vecchia Direttiva 2006/42/CE, non si può non cogliere il senso di una robusta e necessaria innovazione.
Se devo isolare solo 3 pti direi:
Per come la vedo io, è un enorme balzo in avanti, rispetto ad una Direttiva ormai datata.
Ovviamente, il testo potrà essere migliorato e subire modifiche ed integrazioni fino al giorno della sua pubblicazione definitiva. Ma l'impianto generale, probabilmente, non sarà stravolto.
Per chi si occupa di Documentazine Tecnica (sarebbe meglio dire di "informazioni per l'uso" di un prodotto, come stabilito dallo standard 82079) si aprono nuove sfide: la documentazione in formato elettronico consente nuove possibilità, e l'integrazione della macchina con nuove tecnologie implica che il perimetro delle conoscenze da mettere in campo si allarga notevolemente.
Avremo modo di riprendere il tema. Per ora, è tutto.
Leggi questo articolo...Ieri nella mia mail-box è arrivata questa offerta di lavoro (ho camuffato o tagliato informazioni che la rendessero troppo facilmente riconoscibile e i nomi di alcuni ben noti tools...):
Position
At XXXXXXXXXXXXXX, we create software that will enable our team to manage thousands of vehicles and customers on a daily basis. As an API technical writer, you play a key role in building our product by creating useful and engaging software documentation. You have the chance to join this team early on and...
Objectives
Best software to support business: Together with your team, you ship new features.... delivering the best software possible for our customers and business units
Strive for excellence: You strive to deliver the best possible experience for our users...
Providing beautiful software documentation: You help your engineering colleagues by writing high-quality and easy-to-understand documentation for the appropriate audiences
Your qualification
You have a Bachelor’s degree or equivalent. 3+ years creating API documentation in an agile development environment. Passion for creating useful and engaging software documentation with a strong customer-centric focus. Ability to work with API documentation tools such as..., or other docs-as-code approaches. Comfortable understanding codes in one or more programming languages, such as NodeJS or Python...JavaScript...
Experience in relevant product areas (e.g. eCommerce or B2C, SaaS platforms). Usability and testing skills with patience in problem-solving and troubleshooting. Talent in creating visual content using... Meticulous attention to detail and joy in precise working. You have a “never-stop-learning” attitude and a desire to develop and grow. You are fluent in English.
Recentemente ho avuto l'onore ed il piacere di essere intervistato, insieme a Sissi Closs, da Ferry Vermeulen. L'intervista è stata registrata in un podcast di circa 90 minuti che potete ascoltare (e scaricare) da questo link.
Non voglio anticiparvi i dettagli di questa conversazione, dove emergono tutte le questioni principali che vanno indirizzate nella definizione delle migliori strategie per la documentazione del software.
Abbiamo parlato di Minimalismo, processi Agile, SaaS, documentazione Task Oriented, riuso dei contenuti, standard ISO (in particolare dello standard 26514 ed 82079), standard tecnici e linguistici, CCMS e altro ancora.
In 90 minuti abbiamo provato ad inquadrare un argomento estremamente complesso e spero che possiate trarne indicazioni utili, in special modo se state iniziando ad orientarvi sul tema.
Ferry è già noto ai lettori di questo blog, perché in passato ho commentato alcuni suoi straordinari articoli, tra cui:
Definizione della Dichiarazione di Conformità
Intervista sul Minimalismo al Prof. Van der Meij
Ferry Vermeulen è il Direttore Tecnico di INSTRKTIV; il blog di INSTRKTIV è tra i migliori blog al mondo per quanto riguarda le tematiche sulla Comunicazione Tecnica.
Ferry è anche membro, come me, dell'Advisory Board for Legislation and Standard (ABLS) della Tekom Europe.
Anche la Prof.ssa Sissi Closs fa parte dell'ABLS, ed è da molti anni un punto di riferimento per i suoi studenti e per tutti i professionisti del nostro settore.
Con Sissi (e con Andrea Gocke) abbiamo anche scritto un articolo "a 6 mani" sullo standard ISO/IEC/IEEE 26515.
Che dire di più? Scaricate il podcast e buon ascolto!
Leggi questo articolo...... forse oggi ha voluto riprendersi la sua "Mano".
"...perché la vita è un brivido che vola via...
...è tutto un equilibrio sopra la follia..."
V.Rossi Leggi questo articolo...Cos' è un chatbot? E' un software in grado di simulare una conversazione, consentendo agli utenti di interagire con applicazioni web e dispositivi digitali, come se il software fosse una persona reale.
Da alcuni anni se ne parla (spesso "a vanvera"), anche in contesti di associazioni professionali ... poco professionali.
Molti hanno provato a cavalcare l'onda dell'argomento "cool", quello che "fa figo" se in mezzo ad un discorso da salotto pronunci la parola "chatbot" (ma lo stesso vale anche per "blockchain", "machine learning", etc).
Risultati? Spesso pessimi.
Potete costruire chatbot semplici, magari basati su approcci molto datati, come i "decision-tree" oppure chatbot più flessibili, basati su motori di intelligenza artificiale (AI) e potete progettare sofisticati assistenti digitali personalizzati in diversi settori.
Del resto, se i maggiori player mondiali stanno investendo in piattaforme conversazionali e non da ora, come indica Gartner, significa che esiste un mercato potenziale notevole e ancora disponibile.
Ma non si può improvvisare.
Progettare un chatbot non è roba per apprendisti stregoni e bisogna mettere in campo competenze in diverse aree:
.... e molto altro ancora.
Insomma, serve prima di tutto una metodologia o se preferite una "mappa".
Se volete avere un'introduzione al metodo di lavoro che necessita per progettare un chatbot, date un occhiata al blog di Technically Write IT, uno dei blog più interessanti nel campo della Comunicazione Tecnica.
Qui potete trovare tre articoli che vi danno"la mappa", inquadrando le questioni essenziali.
Come costruire un buon chatbot chiarisce alcune questioni di background e fornisce una sorta di check-list per capire come costruire la vostra content strategy, adattata allo use case che dovete indirizzare.
Come realizzare contenuti efficaci per un chatbot fornisce gli step principali per definire contenuti conversazionali del vostro chatbot e gestire il workflow di progettazione.
Come scegliere una piattaforma per sviluppare un chatbot indica le principali caratteristiche che deve avere una valida piattaforma software e anche un elenco delle più importanti piattaforme oggi disponibili sul mercato.
A questo punto siete in grado di progettare un chatbot?
ASSOLUTAMENTE NO!... ma avete una "mappa" che vi guida a valutare tutti i passaggi fondamentali per poter progettare un chatbot e che vi permetterà di risparmiare tempo ed evitare gli errori più banali.
A presto.
Leggi questo articolo...Il post precedente ha iniziato ad indagare più in profondità la tematica di come documentare le API.
Se avete avuto la pazienza di leggerlo, secondo me nella vostra testa si è accesa una lampadina, la tipica lampadina che precede la formulazione di una serie di domande: