Mi manifesto... ergo sum!

 

Leggi questo articolo...

Spiegare lo standard ISO/IEEE/IEC 26514:2022 agli studenti dell'Università Rennes 2

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

E' stata pubblicata la nuova versione dello standard ISO/IEC/IEEE 26514:2022

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!

Leggi questo articolo...

Sta per uscire la nuova versione dello standard ISO/IEC/IEEE 26514

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:

• Come stabilire di quali informazioni hanno bisogno gli utenti.
• Come definire la presentazione delle informazioni.
• Come preparare le informazioni e renderle disponibili.

La prima parte è dedicata alla descrizione di quello che io chiamo "il processo redazionale", cioè il processo di pianificazione e gestione della produzione delle informazioni.

La seconda parte riguarda invece la realizzazione e la presentazione delle informazioni.

In questo nuovo standard si fa riferimento in diversi punti allo standard EN IEC/IEEE 82079-1:2020, lo standard orizzontale per la definizione delle informazioni associate al prodotto, per qualsiasi tipo di prodotto (quindi anche per i prodotti software).

Eliminando una serie di sovrapposizioni tra il vecchio standard 26514 e il più recente 82079, è stato possibile definire una nuova versione molto più "snella" dello standard 26514.

La prima versione dello standard era stata pubblicata nel 2008, ed era quindi necessario un aggiornamento che includesse le linee guida di base inerenti ad una serie di nuovi argomenti.

Ritornerò sul punto con un articolo molto più dettagliato quando lo standard verrà pubblicato.

Per ora, volevo solo alzare una bandierina per avvisarvi.

Leggi questo articolo...

Pubblicata la bozza del Regolamento Macchine: tra le molte novità, cybersecurity e istruzioni in formato elettronico.

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:

• Armonizzare i requisiti di salute e sicurezza relativi alla progettazione, alla costruzione e al commercio dei macchinari all’interno della UE.
• Eliminare le differenze di applicazione tra i diversi Stati membri, che possono adottare diverse strategie nel recepimento della Direttiva.
• Superare gli evidenti limiti della Direttiva nella gestione di una serie di aspetti associati alle nuove tecnologie.

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:

• Che il prodotto sia correttamente identificato (compresi i riferimenti del fabbricante e dell’eventuale importatore).
• Che la documentazione del prodotto sia presente.
• Che il prodotto non sia stato oggetto di eventi (durante il trasporto o l'immagazzinamento) che possano aver compromesso la conformità dei requisiti di sicurezza.

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:

• L'introduzione di una definizione di "macchina" che si apre alle nuove tecnologie (intelligenza artificiale, cyber security, etc.), che possono introdurre profili di rischio per la sicurezza dell'operatore che utilizza le macchine.
• La presenza di un Ente "esterno" per le attività di risk-assessment di alcuni tipi di macchine o dei sistemi di macchine.
• La possibilità di poter fornire la documentazione del prodotto in formato elettronico, come prima opzione.

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

Documentare le API: le aziende cercano l'Unicorno!

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.

In un precedente articolo vi avevo indicato quali dovessero essere le migliori caratteristiche di un API Technical Writer.

Se rileggete l'articolo e lo confrontate con l'annuncio, vi accorgerete che non vi ho mentito!

Aldilà delle battute, la "API economy" richiede una figura professionale NUOVA o forse potremmo dire una "SPECIALIZZAZIONE" nel campo della Comunicazione Tecnica. I fondamentali classici del technical writing hanno ancora un ruolo ovviamente, ma sono solo LA BASE su cui costruire un nuovo asset di competenze.

Se avete fatto caso, questo annuncio di lavoro è rivolto ad un profilo sostanzialmente junior, che però si è già "infarinato le mani" in questo ruolo. In realtà, non esiste "una scuola" per diventare API Techcnical Writer. 

In Italia non esiste nemmeno un percorso degno di questo nome per imparare le basi del technical writing, ma questa è un'altra conversazione.

In altri termini, le aziende hanno bisogno di Unicorni... che come ben sapete, non si trovano facilmente!

Io mi sono occupato per la prima volta di documentare delle API nel 2005, ma io non faccio giursiprudenza, perchè parto in vantaggio: sono un Ing. Informatico che poi è diventato un Tech Writer.

Tanto per avere un'idea, io sono allineato con tutte le caratteristiche dell'annuncio... tranne le gioventù!

Presto inizierò un nuovo ciclo di articoli sulla API economy e su come si documentano le API.

A presto.

Leggi questo articolo...

Una conversazione sulla documentazione del software con Ferry Vermeulen e Sissi Closs

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

Se esiste un Dio...

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

Volete progettare un Chatbot? Avete bisogno di... una mappa.

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: 

• Fare un assessment molto approfondito dello use case a cui dobbiamo applicare il chatbot.
• Saper scegliere la piattaforma software per progettare il chatbot.
• Definire il decision-tree o individuare il dataset utile per allenare il motore di AI.
• Saper scrivere contenuti "molecolari" (Information 4.0) in uno stile conversazionale.
• Conoscere i principi del NLP (Natural Language Processing) e del Machine Learning

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

Documentare le API: bisogna avere un background tecnico?

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:

• Chi documenta le API deve avere confidenza con lo sviluppo software? 
• Deve saper leggere un frammento di codice scritto in Java o in C++ o in Phyton? 
• Deve saper leggere dentro un oggetto JSON o protobuffer? 
• Deve saper navigare agevolmente dentro un XML? 
• Deve conoscere i codici di ritorno del protocollo HTTP?
• Deve aver confidenza con la gestione di processi di sviluppo Agile e Continous Delivery?
• E, più in generale, deve avere un background tecnico solido?
• In altri termini: deve governare almeno i fondamentali della programmazione o essere addirittura un ex-programmatore? 

La mia risposta è SI!

Mentre un technical writer della "scuola classica" potrebbe sostenere che "il technical writer non deve essere esperto della tecnologia da documentare, anzi proprio per questo sarà più efficace nel suo lavoro".

In teoria, possiamo amabilmente discutere di tutto.

In concreto, la mia esperienza mi dice che in certi ambiti tecnologici, il comunicatore deve avere "le mani in pasta" rispetto alla tecnologia. Forse è eccessivo sostenere che debba addirittura essere un ex-programmatore, ma deve di certo padroneggiare tutte le necessarie conoscenze.

Questo è tanto più vero quanto più siamo immersi dentro flussi di lavoro Agile, che alimentano processi di Continous Delivery, dove i tempi di sviluppo della documentazione sono indistinguibili dal ciclo di sviluppo del software e sono estremamente "strettti". 

In tali contesti, con cicli di lavoro di 3 settimane, non c'è molto tempo per "intervistare gli SME", produrre 2 o 3 draft da validare, fare la review linguistica/terminologica, sviluppare la grafica a supporto ed altri passaggi classici dei processi di documentazione.

O meglio: si DEVE FARE tutto questo ma molto più velocemente, in "presa diretta", senza rete. E con molta più "qualità intrinseca", proprio perchè c'è meno tempo anche per rimediare agli errori.

Questo ci obbliga a dover avere una certa "conoscenza" della tecnologia che stiamo documentando, perchè questo ci permette di essere più veloci... e la velocità è un valore.

Non siete convinti? 

Mi avvalgo ancora del report di SmartBear per darvi ulteriori elementi.

QUALI SONO I MAGGIORI OSTACOLI ALLA PRODUZIONE DI API DI QUALITA'?

Le prime due risposte, con il 52% e il 48% delle risposte, vanno a coprire esattamente la mia tesi.

Se non foste convinti, anche la 3^ e la 4^ risposta vanno nella stessa direzione.

Le prime 4 risposte influenzano notevolmente anche i processi di documentazione tecnica.

Le risposte dalla 5^ alla 7^ invece sono più incentrate sull'integrazione di tools, sistemi e processi aziendali.

Tutte queste risposte evidenziano che la qualità delle API prodotte nel nostro processo aziendale, che coinvolge anche la relativa documentazione, ruotano su due elementi principali:

• La competenza e l'esperienza tecnica specifica.
• La velocità di esecuzione del delivery (o se preferite i tempi di realizzazione sempre molto ridotti tra due rilasci successivi).

Se volete avere un primo contatto con il paradigma "Docs as Code" che sintetizza le idee che vi ho illustrato in questo post, date un occhio a questa miniera d'oro di spunti.

A presto.

Leggi questo articolo...