Documentazione degradante: come gestirla?

Importante : non abbiamo alcun problema con la documentazione del codice sorgente . Questo appartiene al controllo periodico del codice ed è tenuto aggiornato. Il nostro problema è con la documentazione per gli sviluppatori (o, se preferisci, "esterna"), piccoli consigli da programmatore a programmatori che tendono ad essere scritti una volta, spesso lasciati indietro.

Usiamo un sistema simile a wiki per produrre documentazione per programmatori - articoli scritti da programmatori per programmatori che descrivono in modo un po 'più dettagliato come funziona un particolare pezzo di codice. Quelle pagine wiki di solito includono:

• motivazioni alla base delle decisioni di progettazione per parti dell'API (ad esempio; abbiamo fatto questa brutta cosa perché questa particolare libreria di terze parti vuole che le cose vengano fatte in questo modo, perché questa altra biblioteca ..., perché ...)
• spiegazione di come gestiamo particolari compiti comuni (ad esempio, visualizzare un popup banale, che deve fare riferimento a stili di applicazione appropriati, registrarsi nel componente del registro e implementare alcune interfacce per essere automaticamente "scansionato" da altri componenti)
• buone pratiche (soggettivo com'è, in realtà scriviamo queste cose)
• configurazione dell'ambiente, strumenti richiesti e sua configurazione

In generale, principalmente cose legate alla scrittura di codice che non si adattano alla normale documentazione del codice a causa delle sue dimensioni e della natura di post di blog / articolo.

Il problema

Per quanto riguarda l'introduzione di questo sistema sembrava una buona idea qualche mese fa, oggi sento che sta causando più problemi di quanti ne risolva. Per esempio:

• le persone fanno scrivere articoli ... ma una volta il codice modificato, aggiornamento wiki segue raramente
• molti articoli da grattare , scritti da qualcuno in fretta e lasciati così
• anche se la richiesta di articoli di solito proviene dal responsabile del progetto, non viene quasi mai verificata la correttezza / composizione - che a volte si traduce in una scarsa qualità

Il solito degrado. Il codice è cambiato, wiki rimane lo stesso. La prossima volta che qualcuno cerca informazioni, quello che trova di solito è un mucchio di cose obsolete e di bassa qualità - e si sta chiedendo cosa sta succedendo, se le cose che ha trovato sono accurate o (anche peggio) quali sono. E ciò che doveva aiutare, finisce per fare il contrario.

Al momento sembra che le persone siano consapevoli del problema, incluso il responsabile del progetto, ma a quanto pare nessuno sembra preoccupato di farci qualcosa (o ha cose più interessanti da fare).

Il mio pensiero iniziale era di buttare tutto nell'oblio (dopo che mi sono stato morso da "punte" obsolete poche volte di seguito), ma suppongo che potrebbe essere troppo estremo. Alcune informazioni sono degne di nota e possono essere lette a volte, ma il problema è sempre lo stesso: come gestisci la sua "attualità" ? È stato in qualche modo collegato al codice sorgente (quindi quando viene verificata la versione aggiornata del file, l'autore dell'articolo viene informato che potrebbe essere necessario rivedere il codice / articolo)? La persona designata "veglia" su di base ogni giorno? Fare pulizie regolari?

Sembra che tu stia documentando troppe curiosità nella wiki.

Documentare blocchi di codice e metodi nel codice . Cerca di rendere il tuo codice auto-documentante in modo da non dover fare molti commenti. Anche scrivere test unitari può essere d'aiuto.

Documentare le decisioni di progettazione e l'architettura con una granularità più elevata nella wiki, quindi la wiki non ha bisogno di cambiare spesso o impiegare molto lavoro per cambiare. Se molte persone del tuo team conoscono già l'architettura e il team non sta crescendo rapidamente, potrebbe non esserci un buon motivo per documentarli, il confronto diretto è spesso il miglior trasferimento di conoscenze.

Riscrivi o elimina immediatamente le informazioni non aggiornate , come il codice morto più a lungo rimane più difficile da individuare e più si accumula. Se non hai tempo basta cancellarlo e contrassegnare l'articolo come da rielaborare, ti rallenta e viene comunque archiviato nel controllo versione.

Documentare le procedure automatizzandole in uno script o in un file di installazione. Altrimenti, tienili nel 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 le persone vogliono condividere opinioni e consigli personali, crea un blog aziendale per questo. Probabilmente non vogliono che i loro articoli vengano modificati e nessuno li modificherà comunque, quindi non lasciare che ingombrino il wiki.

La documentazione deve essere trattata come consegnabile e quindi soggetta alle regole di tracciabilità e accettazione, nonché al periodo di tempo adeguato da sviluppare.

Non è raro vedere la gente "aspettarsi" che la documentazione del software venga data, quando non lo è.

Radicale ma efficace. Se qualcuno ha scritto un nuovo modulo ma non lo ha documentato, riaprire l'attività nel tracker dei problemi e se è necessario impedire la spedizione di tutto il codice sorgente non documentato. Se permetti agli sviluppatori di trattare la documentazione del codice sorgente come un male necessario, finirai con frammenti di documentazione frammentaria e obsoleta.

Nel mio recente progetto tendiamo a tracciare almeno tutte le librerie di terze parti necessarie. Se qualcuno introduce una nuova libreria, ma non è documentata, eseguiamo il rollback della soluzione fino a quando 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.

motivazioni alla base delle decisioni di progettazione per parti dell'API

Ciò è particolarmente importante per essere vicini al codice. Come in, nello stesso file di origine. In questo modo, sarà un po 'più difficile ignorare ogni volta che qualcuno tocca il file e richiedere un minor numero di invii a TheDailyWTF da parte di persone che non sanno che esiste la documentazione esterna.

Il solito degrado. Il codice è cambiato, wiki rimane lo stesso.

È qui che la "documentazione eseguibile" - unit test - diventa molto utile. Se il codice cambia e i test non cambiano con esso, la build si interrompe. Naturalmente, scrivere test come documentazione richiede alcune abilità. Ma anche scrivere (buona) documentazione esterna.

Un buon modo per affrontare il problema è renderlo parte del processo. Se si dispone di una traccia del codice per / fare riferimento alle pagine pertinenti sul wiki, uno sviluppatore può facilmente scoprire cosa potrebbe essere necessario aggiornare. Inoltre, rendere i revisori responsabili in una revisione del codice per assicurarsi che il wiki sia aggiornato (per quanto riguarda l'aggiornamento).

Un altro modo per aggiungerlo come parte del processo - poiché stai usando un modello agile, parte del processo di pianificazione per le iterazioni, potrebbe essere quello di aggiornare le modifiche pianificate nel wiki. Il wiki quindi funge da risorsa 'ecco come dovrebbero funzionare le cose'.

Se si utilizza un linguaggio .net, consultare ( Sandcastle ) che accetta la documentazione XML (/// in C #) e la converte in formato di aiuto MSDN.

Il formato include descrizione, commenti e ha la possibilità di includere esempi di codice, nonché alcune altre funzionalità. È possibile eseguire l'output nei formati .CHM, .HsX, .MSCH e HTML / ASP.NET. Il progetto effettivo viene aggiunto alla soluzione e creato sul server di compilazione. Lo abbiamo fatto e distribuito su un sito Web ogni rilascio, e i consumatori lo adorano perché la documentazione è rilevante per il 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 contrassegnati privati ​​e interni.

Questa è diventata l'unica documentazione che utilizziamo, poiché le motivazioni e le stranezze sull'uso 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) Note e documenti senza codice.

1) Il codice.

Prova a renderlo autocomponente. In passato ho scoperto 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

Fai un codice che assomigli di più 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 "chi ha fatto cosa quando".

2) Il non codice

Utilizzare un formato wiki e markdown per conservare queste informazioni. Renderlo parte del lavoro. Pubblicizzalo, pubblicalo e blog. Organizza una riunione settimanale o mensile standard per esaminare le cose vecchie e nuove. Rendilo un mantra che quando qualcuno chiede qualcosa viene data la risposta ... insieme al pensiero "dovrebbe essere nella wiki per la prossima volta che qualcuno chiede?"