Documentazione degradante: come affrontarla?

Sembra che tu stia documentando trivia nel wiki.

Blocchi di documenti di codice e metodi nel codice . Cerca di rendere il tuo codice auto-documentante in modo da non dover fare molti commenti. Anche i test delle unità di scrittura possono aiutare.

Decisioni progettuali del documento e architettura a granularità più elevata nella wiki, quindi il wiki non ha bisogno di cambiare spesso o impiegare molto lavoro per cambiare. Se molte persone della tua squadra conoscono già l'architettura e il team non sta crescendo rapidamente, potrebbe non esserci un valido motivo per documentarle, il confronto diretto è spesso il miglior trasferimento di conoscenza.

Riscrivi o cancella immediatamente le informazioni non aggiornate , come dead-code più a lungo rimane più difficile da individuare e più si accumula. Se non hai tempo, basta eliminarlo e contrassegnare l'articolo come necessario per la rielaborazione, in quanto rallenta e viene comunque memorizzato nel controllo della versione.

Procedure del documento automatizzandole in uno script o in un file di installazione. Altrimenti, tienilo nella wiki, ma ogni volta che qualcuno usa una procedura dal wiki, digli di provare a migliorare l'articolo o automatizzare parti del processo.

Gli articoli del blog appartengono ai blog . Se la gente vuole condividere le proprie opinioni e i propri consigli, creare un blog aziendale per questo. Probabilmente non vogliono che i loro articoli vengano modificati e nessuno li modificherà comunque, quindi non lasciarli ingombrare il wiki.

La documentazione deve essere considerata come un deliverable e quindi soggetta alle regole di tracciabilità e accettazione, oltre a fornire il tempo necessario per lo sviluppo.

Non è raro vedere le persone "aspettarsi" che la documentazione del software sia un dato, quando non lo è.

Radicale ma efficace. Se qualcuno ha scritto un nuovo modulo ma non lo ha documentato, riapri l'attività in issue tracker e, se necessario, impedisci la spedizione di tutto il codice sorgente non documentato. Se permetti agli sviluppatori di trattare la documentazione del codice sorgente come se fosse il male necessario, finirai con frammenti di documentazione frammentaria e obsoleti.

Nel mio recente progetto tendiamo a tenere traccia di tutte le necessarie librerie di terze parti. Se qualcuno introduce una nuova libreria, ma non è documentata, ripristiniamo la soluzione finché non viene introdotta la documentazione. Senza un approccio così radicale ci sarebbe il caos. Ad esempio, uno sviluppatore inesperto potrebbe utilizzare una libreria la cui licenza è in conflitto con la licenza del nostro software.

Se qualcosa sta cambiando rapidamente, non dovrebbe essere mantenuto al di fuori del codice.

motivations behind design decisions for parts of API

Questo è particolarmente importante per stare vicino al codice. Come in, nello stesso file sorgente. In questo modo, sarà un po 'più difficile ignorare ogni volta che qualcuno toccherà il file e spingerà meno richieste a TheDailyWTF da parte di persone che non sanno che la documentazione esterna esiste.

The usual degradation. Code changed, wiki stays the same.

Questo è dove la "documentazione eseguibile" - unit test - diventa molto utile. Se il codice cambia e i test non cambiano insieme a esso, la costruzione si interrompe. Ovviamente, scrivere test come documentazione richiede un po 'di abilità. Ma anche la scrittura (buona) documentazione esterna.

Un buon modo per affrontare il problema è renderlo parte del processo. Se si dispone della traccia del codice per / riferimento alle pagine pertinenti sul wiki, uno sviluppatore può facilmente scoprire cosa potrebbe essere necessario aggiornare. Inoltre, responsabilizzare i revisori in una revisione del codice per accertarsi che il wiki sia aggiornato (riguardo all'aggiornamento).

Un altro modo per aggiungerlo come parte del processo - dal momento che stai usando un modello agile, parte del processo di pianificazione per le iterazioni, potrebbe essere quello di aggiornare le modifiche pianificate nella wiki. Il wiki funge quindi da risorsa 'questo è il modo in cui le cose dovrebbero funzionare'.

Se stai usando una lingua .net, guarda ( Sandcastle ) che prende la documentazione XML (/// in C #) e lo converte in formato di guida MSDN.

Il formato include la descrizione, i commenti e ha la capacità di includere esempi di codice, oltre ad altre caratteristiche. È possibile stampare in formati .CHM, .HsX, .MSCH e HTML / ASP.NET. Il progetto attuale viene aggiunto alla tua soluzione e costruito sul server di build. Abbiamo fatto questo e distribuito su un sito Web ogni versione, e i consumatori lo adorano perché la documentazione è pertinente al rilascio e costantemente aggiornata.

Puoi anche specificare cosa includere nella documentazione. Attualmente abbiamo 2 progetti: uno per i consumatori esterni che include solo i contratti e gli articoli appropriati (classi, enumerazioni, ecc.) E uno per gli sviluppatori interni che include tutto nell'API, inclusi gli elementi privati e interni contrassegnati.

Questa è diventata l'unica documentazione che usiamo, poiché le motivazioni e le stranezze sull'utilizzo dell'API possono essere incluse nella sezione Commenti della documentazione. Il processo funziona bene dove lavoro.

Mi concentrerei su due aree, 1) Il codice. 2) Nessuna-code note e documento.

1) Il codice.

Prova a renderlo autocopiante. In passato ho trovato che era spesso consigliato ma raramente spiegato bene, quindi ...

Invece di questo tipo di pseudo codice:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Il codice sembra più simile a questo:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Utilizza il controllo del codice sorgente per tenere traccia delle informazioni su "chi ha fatto cosa quando"

2) Il non-codice

Usa un formato wiki e markdown per mantenere queste informazioni. Rendilo parte del lavoro. Pubblicalo, pubblicalo e bloggalo. Impostare una riunione settimanale o mensile standard per rivedere le cose vecchie e nuove. Rendilo un mantra che quando qualcuno chiede qualcosa viene data la risposta ... insieme al pensiero "dovrebbe essere nel wiki per la prossima volta che qualcuno ti chiede?"