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:
-
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ò.
-
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?