giovedì 29 ottobre 2020

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.

Condividi


Articoli correlati per categorie



Nessun commento:

Posta un commento