sabato 1 maggio 2021

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

lunedì 5 aprile 2021

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