[ad_1]
La documentazione del codice non è mai stata considerata divertente. Forse è ora di cambiare la situazione.
Documentare il codice è spesso visto come un compito arduo, ma necessario. Per molti sviluppatori, questo processo è dispendioso in termini di tempo e di drenaggio del cervello, il che è l’esatto opposto di come dovrebbe essere. Una parte fondamentale del processo di documentazione, ovvero la creazione di immagini e diagrammi, potrebbe essere la chiave per una migliore comunicazione tra gli sviluppatori.
La creazione di diagrammi dovrebbe essere un’esperienza di apprendimento dinamica, utile e divertente. Dovremmo considerare i diagrammi come straordinari strumenti di comunicazione visiva che ci aiutano a risparmiare tempo, ad anticipare potenziali problemi nel nostro codice e a collaborare con colleghi di diverse professioni.
Allora cosa ci trattiene? Per prima cosa, il panorama degli strumenti e delle piattaforme per la creazione di diagrammi è affollato di soluzioni che non si adattano del tutto alle nostre esigenze. La maggior parte dei software dà priorità alla funzionalità o alla presentazione, ma raramente a entrambe.
Diagrammare il tuo codice dovrebbe essere più simile a Google Docs. I colleghi dovrebbero essere in grado di lavorare sugli stessi diagrammi in tempo reale, senza preoccuparsi di duplicati o versioni obsolete. Dovremmo essere in grado di commentare, suggerire e chattare mentre costruiamo sequenze, diagrammi di flusso e diagrammi del percorso dell’utente. Diagrammi dinamici e ben curati possono rendere il nostro codice più pulito, sostituire le e-mail che si scambiano messaggi di posta elettronica e mantenere allineati interi team, anche mentre lavorano in remoto.
Se riusciamo a trovare gli strumenti e i flussi di lavoro giusti, c’è anche la possibilità che i diagrammi diventino la forma principale di comunicazione sul posto di lavoroper tutti, dai programmatori agli esperti di marketing fino agli avvocati.
Realizzare il potere dei diagrammi per la documentazione
Anni fa lavoravo sulla logica di gestione delle campagne per un’azienda di e-commerce. Questa logica era complessa e ogni volta che iniziavo a lavorarci dovevo ripassare il codice per spiegarlo a varie parti. Questo è diventato vecchio, veloce.
È stato allora che mi ha colpito: perché non creo un diagramma di flusso per delineare i passaggi?
Ha funzionato. Invece di scorrere tutto il codice, potrei semplicemente aprire il mio diagramma di flusso e tutti, tecnici o no, riuscirebbe a capire. Era un sistema di controllo per la discussione.
Mi sono reso conto che la prima volta che avevo impostato gli stati in un flusso di pagamento, avevo ingegnerizzato eccessivamente qualcosa che era irragionevolmente complesso. Se avessi costruito prima il diagramma di flusso, l’avrei notato prima di andare troppo lontano.
Questa è la bellezza dei diagrammi; forniscono un progetto che ti consente di comprendere l’insieme di ciò che stai costruendo prima di fare progressi.
Cosa c’è di sbagliato nel modo in cui attualmente stiamo costruendo le immagini?
Comprendere l’importanza di diagrammi efficaci è una cosa. In realtà seguirli e crearli è un’altra cosa.
In generale, gli sviluppatori non dispongono degli strumenti giusti per creare elementi visivi per il proprio codice in modo rapido ed efficiente. Emergono tre problemi:
Tempo: il processo richiede troppo tempo.
I team di sviluppo trascorrono troppo tempo cercando di creare diagrammi e comunicare il loro messaggio, il che elimina il tempo che hanno a disposizione per scrivere effettivamente un buon codice e portare avanti i progetti.
Creare progetti in Powerpoint o in qualche altro strumento sembra goffo. Pochissimi si divertono a disegnare frecce e caselle con il mouse. Aggiornare i diagrammi per cambiamenti costanti diventa un ladro di tempo.
Controllo della versione: i diagrammi e il codice non sono sincronizzati.
Forse crei un diagramma che esiste in posti diversi: nel tuo strumento per la creazione di diagrammi, come screenshot nel codice stesso o in una presentazione separata. Cosa succede quando apporti una modifica a una versione di quel diagramma? All’improvviso le altre versioni risultano obsolete; quegli screenshot statici non si aggiornano da soli. Diventa più difficile fidarsi della propria documentazione e ora è necessario dedicare tempo alla valutazione della documentazione rispetto al codice originale (vanificando in primo luogo lo scopo della documentazione).
Presentazione: ci manca la zona Goldilocks.
Non abbiamo trovato un equilibrio tra i diagrammi visivamente piacevoli e quelli che comunicano efficacemente. Molti di noi si sono imbattuti in un “diagramma lanuginoso”: qualcosa che sembra fantastico, ma elude le questioni fondamentali e richiede troppo tempo per essere creato. Se il tuo diagramma non è abbastanza robusto, non sarà efficace per la comunicazione, soprattutto quando lavori tra reparti diversi.
Come potrebbe essere un futuro con strumenti di creazione di diagrammi migliori?
La prossima generazione di piattaforme per la creazione di diagrammi dovrà affrontare questi tre problemi fondamentali. Una volta arrivati a questo punto, gli sviluppatori otterranno una migliore qualità nella loro documentazione. Ma che aspetto ha in realtà?
Vera connettività tra diagrammi e codice
Gli sviluppatori hanno bisogno di un’unica fonte di verità per i loro diagrammi: un unico archivio che elimini lo stress sul controllo della versione. Dovremmo essere in grado di apportare una modifica a un diagramma in un punto e aggiornarlo automaticamente ovunque appaia, nel codice e altrove.
Collaborazione più significativa
Torniamo all’esempio di Google Docs. I diagrammi dovrebbero essere uno spazio di lavoro dinamico e basato sul Web in cui i team possono farlo collaborare in modo sincrono o lasciate commenti reciproci in un flusso di lavoro asincrono, il che sarebbe particolarmente utile con la forza lavoro remota che è più distribuita. Ad alcuni membri del team potrebbero essere concesse autorizzazioni diverse, consentendo loro di modificare e visualizzare solo le parti del diagramma su cui stanno lavorando.
Utilizzando un diagramma, i team di sviluppo possono avere una visione comune dei propri flussi di lavoro, il che riduce il rischio di incomprensioni e facilita l’individuazione degli errori in un gruppo durante la convalida congiunta di un progetto.
La documentazione è in realtà… divertente!
Suo scientificamente provato; il divertimento è essenziale per un ottimo posto di lavoro. Lavoriamo meglio quando ci divertiamo e la documentazione dovrebbe contribuire a creare buone vibrazioni.
La costruzione dei diagrammi dovrebbe sembrare una magia, non un esasperante gioco di clic e trascinamento con il mouse. Dovremmo essere orgogliosi delle immagini che creiamo perché sono cristalline, hanno un bell’aspetto e non richiedono un’eternità per essere realizzate.
Non si ferma agli sviluppatori: il caso della comunicazione visiva
Come sai, la documentazione dei processi non è un’esclusiva degli sviluppatori. I diagrammi possono fornire un linguaggio comune tra le professioni poiché comunicano i processi aziendali.
In teoria, chiunque abbia bisogno di comunicare idee dovrebbe essere in grado di farlo attraverso un diagramma robusto ma semplice da realizzare. Le e-mail lunghe possono essere sostituite con immagini. I manuali e le guide pratiche possono essere ridotti, con grafici che sostituiscono grandi porzioni di testo.
Inizieranno i posti di lavoro parlando per diagrammi – e chiunque, dallo sviluppo aziendale alle risorse umane all’ingegneria, può unirsi al divertimento. Le persone collaboreranno da luoghi diversi e i colleghi potranno costruire insieme.
Viviamo in un mondo visivo. Anche il futuro del lavoro dovrebbe essere visivo.
[ad_2]
Source link
