Mantenere documentazione / manuali aggiornati in un progetto in rapida evoluzione

5

Sfondo

Lavoro su un progetto relativamente grande (~ 570 KLOC) in un team relativamente piccolo (ex 5 sviluppatori, ora 2). Grandi quantità di codice possono apparire e poi svanire in mesi; ad esempio, alcuni anni fa una banca d'investimento ha lanciato una nuova borsa, quindi l'ha chiusa 7 mesi dopo: migliaia di LOC sono state scritte per supportare l'interfaccia di tale scambio, quindi cancellate.

Per aiutare le operazioni e supportare sia i team che i nuovi sviluppatori, abbiamo un wiki interno (un DokuWiki modificato, se è importante) con cose come le specifiche retrospettive (stiamo scrivendo le specifiche man mano che andiamo, purtroppo) e quali varie impostazioni , flag e codici di stato significano e fanno.

Problema

A causa del rapido sviluppo, tuttavia, gran parte del nostro contenuto wiki diventa obsoleto in mesi, se non settimane. E non è così semplice come aggiornare una singola sezione wiki su qualunque componente venga modificato; con numerosi componenti di interblocco, la modifica di una cosa, come un'impostazione nella componente di trading algoritmico, potrebbe richiedere la visualizzazione di un centinaio di riferimenti a questa impostazione e / o componente nella wiki, molti dei quali potrebbero richiedere l'aggiornamento di sezioni.

Il problema principale, credo, è motivazionale. Gli sviluppatori sanno che qualunque cosa scrivano ha una buona possibilità di diventare presto obsoleto, quindi raramente vale la pena (né è pratico) di andare a cercare attraverso il wiki per aggiornare tutti i pezzi rilevanti, specialmente quando 2 o 3 giorni dopo potrebbe esserci una richiesta per cambiare, ad esempio, il formato di un'impostazione o anche la sua funzionalità. Ciò porta alla diffidenza nei confronti della wiki, anche tra noi, non siamo mai sicuri che ciò che stiamo leggendo in effetti descriva le ultime funzionalità. E questo, secondo me, alimenta un circolo vizioso simile alla teoria delle finestre rotte : la percezione del disordine demotiva qualsiasi azione a riportare ordine.

Idea

La mia idea era di migrare la wiki a qualcosa di più simile a Stack Exchange, ad esempio personalizzando Question2Answer . Per due motivi:

  1. Spero che mettendo tutte le informazioni in Q & Un modulo incoraggi la documentazione da scrivere con il pensiero in mente, "A quale domanda sto cercando di rispondere? Chi sto cercando di aiutare?" Questo non è correlato a questo post, però.

  2. Ancora più importante, la mia idea è di usare i tag, un tag per ogni componente, ogni impostazione, ogni termine aziendale, ecc., in modo che più semplice trovi post che devono essere aggiornati, piuttosto che passare attraverso ogni istanza di una parola chiave e le ricerche di parole chiave sono già contestualizzate, da sole.

Domanda

Prima di passare a questa idea, tuttavia, ho pensato che avrei potuto trarre beneficio dai consigli se qualcun altro ha lavorato in tale contesto. Sono aperto a tutte le idee e le alternative!

Come mantenere aggiornata la documentazione con riferimenti incrociati in un progetto in rapida evoluzione?

    
posta Andrew Cheong 07.03.2014 - 23:50
fonte

4 risposte

7
  1. Se possibile, riduci o elimina la necessità di documentazione scrivendo codice chiaramente comprensibile anziché scrivere documentazione per spiegare il codice ottuso.

  2. Conservare la documentazione il più vicino possibile al codice effettivo che descrive. Nella maggior parte dei casi, ciò significa inserire la documentazione nel codice stesso. Alcune piattaforme di sviluppo (ad esempio Visual Studio) dispongono di strumenti esterni che possono essere utilizzati per convertire i commenti del codice in altre forme leggibili, come i file della guida e le pagine Web.

  3. Limita la documentazione ai problemi di integrazione e all'architettura generale. Lascia che il codice effettivo parli da solo.

risposta data 08.03.2014 - 00:06
fonte
3

La risposta di Robert Harvey è già buona, ma mi piace aggiungere un reamrk sul tuo piano attuale. Allo stesso modo in cui il codice cambia da versione a versione, allo stesso modo in cui la documentazione deve essere modificata. Ma se i tuoi documenti sono in un sistema Wiki o "Stack Exchange", non puoi integrare questo bene nel tuo sistema di controllo della versione (VCS). Quindi suggerisco caldamente di non separare i documenti dal resto dell'albero dei sorgenti: i documenti dovrebbero essere versionati e taggati insieme alla corrispondente versione del codice. Uno strumento come doxygen può essere usato per scrivere i tuoi documenti (compresi i documenti degli utenti finali) in forma di testo (adatto per qualsiasi VCS) e generare documenti ben formattati.

    
risposta data 08.03.2014 - 01:27
fonte
1

Intent è un prodotto sperimentale che tenta di risolvere precisamente questo problema, attualmente in un ambiente Eclipse / Java. L'obiettivo sembra essere quello di avere una documentazione strongmente tipizzata, o forse unitamente testata. Qualsiasi parte della documentazione che diventi incoerente con il corrispondente codice sorgente verrà contrassegnata come un errore, proprio come il codice che chiama una funzione che non esiste più.

Questo risolve il problema con la documentazione; non poterlo fidare perché potrebbe essere più vecchio, o forse più recente, del sistema. E a differenza della semplice generazione di documenti (javadoc / doxygen), la documentazione è strutturata attorno alla leggibilità, non al codice sorgente.

Promettendo come sembra, sarei interessato se qualcuno avesse qualche esperienza del mondo reale con esso ...

    
risposta data 08.03.2014 - 02:03
fonte
-1

Non conservando la documentazione, il codice sorgente diventa un disastro e nel tempo il costo del cambiamento aumenta fino a diventare troppo costoso per apportare modifiche e manutenzione minori. A questo punto hai trasformato il valore corrente del tuo codice (500K SLOC vale quanto in questo momento) in qualcosa che non vale niente.

Supponiamo che il tuo codice abbia un valore di $ 5 milioni ora, e che oltre 10 anni permetti se degradare per non avere alcun valore - che è $ 500k / anno persi. Spendere forse $ 100K per mantenere il suo valore è economico.

Non è altro che semplice economia aziendale. Spendi un po 'di denaro adesso sulla manutenzione preventiva per ridurre i costi e la perdita di valore in futuro. Nessuna differenza che dipingere un ponte in acciaio, solo per ricominciare dall'inizio appena hai finito.

    
risposta data 08.03.2014 - 07:43
fonte

Leggi altre domande sui tag