Come posso convincere i miei manager a far rispettare gli standard di documentazione?

Se il tuo obiettivo è in qualche modo convincere l'altro team a sedersi e commentare il codice e fornire la documentazione, penso che ti verrà una grande delusione. Non c'è modo in cui una squadra sta per aprire la base di codice e iniziare a commentare le cose per la tua squadra in massa. Anche se in qualche modo fossero costretti a farlo, il valore sarebbe dubbio al meglio.

Penso che un approccio più pragmatico sia quello di ottenere la collaborazione di alcuni sviluppatori chiave originali che possono guidare la tua squadra attraverso la base di codice e che sono disposti a tornare in base alle necessità. Chiamala una "fase di transizione".

La documentazione dovrà essere scritta dalla tua squadra, ma la buona notizia è che saranno molto più motivati a farlo bene rispetto a una squadra che deve svolgere tale compito prima di "gettarla oltre il muro".

Il problema è che il problema è soggettivo. Avrai sempre persone che pensano che dovresti scrivere codice così chiaro che non ha bisogno di commenti o che qualsiasi buon programmatore degno di questo nome dovrebbe essere in grado di decifrare i tuoi algoritmi.

Se qualcuno crede che non hai bisogno di commenti, probabilmente non li convincerai. Puoi solo sperare di convertire gli indifferenti e ottenere che i non credenti seguano l'esempio semplicemente rimanendo in minoranza. Il che potrebbe significare portare l'esempio di prendersi del tempo per farlo da solo e mostrare la differenza / beneficio dopo averne abbastanza per confrontare e contrastare.

Una soluzione potrebbe essere quella di promuovere l'adozione di qualcosa come doxygen . Il vantaggio è la documentazione sfogliabile per i futuri membri del team da esplorare. Ciò consente di ottenere solo commenti a livello di interfaccia e non di livello di implementazione, ma una volta ottenuta la rotazione è più facile crescere da lì che senza nulla al suo posto.

Altrimenti dovrai solo costruire la documentazione a tuo favore. Riferendosi a più best practice blog o blog aziendali. Google dice che è importante, quindi deve essere!

In definitiva sei tu contro una cultura consolidata e potresti non avere successo.

Buona fortuna!

How can I convince my managers to enforce documentation standards on this other team?

In tal caso, farei appello alla stima degli sforzi per il trasferimento. Vorrei fare uno studio preliminare della documentazione disponibile e riassumere le mie scoperte in un modulo che è leggibile per la gestione.

• "1. Lo strumento di analisi del codice sorgente mostra circa il 10% di commenti, ma dopo la rimozione di prova delle funzioni completamente commentate il valore scende a circa lo 0,5% 2. Presenza di documentazione intranet: 1 pagina di confluenza con circa 1 Kb di testo e due pagine di testo condiviso con 20 righe di testo 3. Caratteristiche tecniche: non trovato 4. Rilevatore di problemi: lo studio della selezione del campione di 5 numeri scelti a caso (# 17, # 31, # 98, # 118, # 234) ha mostrato questi 5. VCS: studiando la selezione del campione di 5 commit scelti a caso (# 1017, # 1031, # 1098, # 1118, # 1234) ha dimostrato che questi sono completamente inutili. "

Successivamente ho presentato alla gestione due stime di sforzi per completare la rimozione : una per il caso se le cose sono così come l'altra nel caso in cui "un'altra squadra" fornisca documenti e questi documenti passare una recensione dal mio team e lasciarli scegliere.

• "Sfida per l'opzione as-is: circa 12 mitico man-months Per un'opzione di revisione documentata e passata: 1 mese per la revisione più 1 mese per la restituzione. "

Non mi sorprenderei se BTW scelga l'opzione come-è (è stato fatto lì - il loro cervello a volte funziona su una frequenza diversa se si cattura la deriva)

Have there been studies or work done to prove that code documentation increases profitability or productivity?

Anche se ci sono studi simili, potrebbero rivelarsi inutili per te. Voglio dire, anche se in qualche modo sarai in grado di imporre standard su questi ragazzi, molto probabilmente troveranno un modo per farlo velocemente (hai menzionato che il gruppo ha dei ragazzi intelligenti vero? ) e ti lasciano con alcune centinaia di kilobyte di spazzatura inutile che si adatta perfettamente al tuo standard qualunque esso sia.