Comunicazione Tecnica — Cheat Sheet

Tag: technical-communication, system-design, documentation, soft-skills, agile, code-review

Livello: intermedio

TL;DR: Strutture e principi per spiegare scelte architetturali, trade-off e incidenti sia a figure tecniche sia a stakeholder di business.

Concetti chiave

Adattare il livello di astrazione all'interlocutore distinguendo metriche di business da dettagli implementativi.

Strutturare ogni decisione complessa esplicitando contesto, vincoli, alternative scartate e trade-off accettati.

Usare il framework STAR (Situation, Task, Action, Result) per raccontare problemi tecnici e progetti passati.

Documentare l'architettura tramite Architectural Decision Records (ADR) per tracciare il contesto e la motivazione.

Comunicare l'impatto di un debito tecnico collegandolo a velocità di rilascio, stabilità e costi operativi.

Spiegare concetti complessi usando analogie concrete prima di scendere nei dettagli di protocollo o algoritmo.

Praticare ascolto attivo: riformulare requisiti ambigui prima di proporre una soluzione tecnica.

Mantenere la scrittura asincrona sintetica, con punti elenco, premesse chiare e azioni richieste esplicite.

Condurre code review separando suggerimenti stilistici non bloccanti da difetti architetturali o di sicurezza.

Gestire comunicazioni di incidente tramite post-mortem blameless focalizzati su cause sistemiche e remediation.

Domande tipiche e risposte pronte

Q: Come spieghi a un product manager perché una feature richiede un refactor preliminare?R: Isolo il collo di bottiglia: spiego che il refactor riduce il rischio di regressioni e abbassa i tempi di rilascio delle funzionalità future correlate.

Q: Come gestisci un disaccordo tecnico su una scelta architetturale all'interno del team?R: Porto la discussione sui dati e sui vincoli oggettivi: redigo un ADR comparativo con vantaggi, svantaggi e costi operativi di ciascuna opzione.

Q: In che modo presenti un'architettura complessa a un executive o a un cliente non tecnico?R: Parto dal problema di business e dall'output finale, usando diagrammi ad alto livello ed evitando dettagli su framework o librerie.

Q: Come comunichi un incidente grave o un downtime a stakeholder interni?R: Fornisco subito stato attuale, impatto sugli utenti, azioni di mitigazione in corso e stima per il prossimo aggiornamento, senza entrare in tecnicismi prematuri.

Insidie e errori comuni

Rispondere a domande di business scendendo immediatamente nei dettagli implementativi di codice o query.

Usare gergo tecnico non condiviso o acronimi interni senza definirli preventivamente.

Giustificare il refactor come necessità di codice pulito anziché come abilitatore di valore e stabilità.

Condividere lunghi blocchi di testo asincroni privi di una sintesi esecutiva iniziale.

Dimenticare di documentare le ragioni che hanno portato allo scarto di un'alternativa tecnica.

Dare per scontato che l'interlocutore condivida il medesimo contesto storico del sistema.

Snippet e comandi

# ADR-001: Scelta del pattern architetturale

## Contesto
Descrizione del problema attuale, dei vincoli di latenza e del carico previsto.

## Decisione
Adozione di un'architettura a eventi asincrona per il disaccoppiamento dei moduli.

## Alternative considerate
- Chiamate REST sincrone punto-a-punto: scartate per forte accoppiamento e rischio cascata timeout.
- Batch processing notturno: scartato per requisiti di freschezza del dato sotto i 5 secondi.

## Conseguenze
- Vantaggi: scalabilità orizzontale indipendente dei consumatori, resilienza ai picchi.
- Trade-off: complessità di tracing distribuito e gestione della consistenza eventuale.

Da ripassare

[ ] Struttura standard di un Architectural Decision Record (ADR)

[ ] Framework STAR per l'esposizione di scenari ed esperienze

[ ] Linee guida per la scrittura di post-mortem blameless

[ ] Definizione di trade-off tra consistenza, disponibilità e complessità di manutenzione