Determinazione della giusta quantità di documentazione

10

Dove lavoro attualmente l'approccio generale è -

evita il più possibile la documentazione

Documenta solo se un team diverso ne avrà bisogno

solo per chiarimenti, non intendo la documentazione del codice - questo lo facciamo, intendo tutta la documentazione che circonda il processo di progettazione - se si tratta di schemi UML o DB, diagrammi di classe e documenti di parole con specifiche e simili. p>

Elencherò il motivo del mio capo per non documentare:

  1. è dispendioso in termini di tempo: concentrati sull'implementazione
  2. se la modifica del progetto - allora la documentazione dovrebbe cambiare, doppio problema
  3. alla fine ottieni solo centinaia di pagine che nessuno vuole leggere, e nessuno lo modifica veramente per tempo non sarà aggiornato
  4. È un dolore - nessuno lo vuole davvero

Ora mi rendo conto che lavoriamo più velocemente, ma ricordo anche il tempo passato qui e mi sono tuffato direttamente in un vecchio codice, senza capire niente.

In realtà, non riesco ancora a ottenere la maggior parte di questo vecchio codice, ea volte quando arrivo vedo molte patch di sviluppatori diversi che cercano di apportare piccole modifiche.

Credo davvero che la mancanza di documentazione promuova questo tipo di patch e la mancanza di comprensione del sistema in senso lato.

la mia domanda è:

Come possiamo bilanciare la documentazione in modo da promuovere la conoscenza continua tra i membri del team ed essere comunque veloce ed efficiente?

    
posta Mithir 02.02.2012 - 15:42
fonte

5 risposte

5

Ho trovato che QUALSIASI documentazione è migliore di NESSUNA documentazione. L'importo appropriato è in genere determinato dalla quantità di tempo che dobbiamo fare, o da quanto odiamo le telefonate e le e-mail di supporto.

Sembra che i membri del tuo team attuale abbiano aspettative irrealistiche nei loro ricordi, o si vergognino delle loro capacità di scrittura e non sono disposti a fare pratica.

Mi rendo conto di essere in minoranza (maggiore inglese che è entrato nell'ingegneria del software in una scuola di specializzazione) qui, perché non trovo la documentazione un lavoro ingrato. È un prezioso strumento professionale. Potrei non trovare la scrittura difficile da fare come alcuni dei miei colleghi, ma è soprattutto perché ho più pratica in questo. Non considero un progetto finito a meno che non abbia documentazione, e di solito lo scrivo per ragioni puramente egoistiche: così posso dare alle persone qualcosa da leggere invece di prendere telefonate ed e-mail, o così posso ricordare di cosa stavamo parlando ultimo mese, o così posso riferirmi a come ho fatto qualcosa se ho bisogno di sostenerlo nel cuore della notte.

Il modo migliore per avvicinarsi alla documentazione è scriverlo COME SI VA, esattamente come scrivere il codice di prova. È sorprendente come alcuni modelli pre-scritti (con intestazioni, stub di codice, ecc.) Possano rendere la documentazione più semplice e veloce da fare. In questo modo puoi acquisire i cambiamenti mentre accade e hai meno possibilità di copertura nel tempo. Sei più efficiente in questo modo, dal momento che puoi fare riferimento alla documentazione in base alle tue esigenze e modificarla lungo il percorso. Fare così in un wiki, ad esempio, rende gli aggiornamenti più facili ed è possibile evitare problemi di versione del documento se il più recente e il più grande è sempre online nello stesso posto e si possono semplicemente inviare collegamenti a persone che hanno bisogno di leggerlo.

Se trascorri un po 'di tempo a documentare, lavorerai TUTTI più velocemente, soprattutto quando qualcuno si unisce al team, dal momento che non dovrà passare tutto il tempo a capire tutto. Capire le cose è una parte divertente del nostro lavoro, ma non è divertente quando devi farlo in fretta per sistemare la produzione. Avremmo tutti risparmiato un sacco di tempo se avessimo scritto un altro paio di note.

Il tuo team ha gli stessi problemi con il test o la scrittura del codice di test? In caso contrario, questa sarà una vendita più facile.

La tua documentazione è utile in molti modi:
1) A te, proprio ora, e ai tuoi colleghi, mentre lavori al progetto.

2) Ai tuoi clienti. Avere documentazione (inclusi diagrammi) che puoi mostrare agli utenti semplifica le discussioni nelle riunioni, specialmente se stai discutendo di sistemi complicati. Anche se la documentazione è incompleta, è un punto di partenza.

3) Alle persone che erediteranno il tuo lavoro (che potrebbe anche essere te, in tre anni). Molti dei miei colleghi più giovani pensano che ricorderanno cose per sempre. So che non lo ricorderò oltre questa settimana se non lo scrivo. Avere documentazione ti evita di dover passare una mezza giornata per ricordare come hai strutturato qualcosa, e dover ricominciare tutto da capo.

4) A te e agli altri, se la situazione diventa politica o controversa. Come qualcuno che prende appunti negli incontri, per tenermi sveglio e combattere la noia, sono spesso stato l'unico con la versione scritta di una decisione. La persona che l'ha scritta vince la disputa. Ricorda questo la prossima volta che qualcuno dice "Ricorda quell'incontro avvenuto lo scorso inverno nella sala conferenze 4, quando stavamo andando oltre X? Fred era lì, e chi è quel tizio della Contabilità?"

    
risposta data 02.02.2012 - 17:03
fonte
4

Negli ultimi miei datori di lavoro, abbiamo avuto un wiki di "sviluppo". Chunk di funzionalità significativi (nuovi feed di importazione / esportazione, come funziona il sottosistema di sicurezza, dove il sistema archivia i documenti caricati, ecc.) Vengono tutti documentati lì. Di solito è un elemento obbligatorio da completare prima della fase di revisione del codice. Di solito c'è un po 'di resistenza all'inizio, ma una volta che qualcuno ha bisogno di andare a cercare un po' di informazioni ed è lì, hai un altro convertito.

Il bello di averlo in un formato wiki è che tu sei molto meno incline a fare tutta la bella formattazione di Word e così via e scrivi solo le informazioni reali che ti servono per salvare. La maggior parte dei pacchetti wiki (se non tutti) ti permetteranno di caricare documenti o immagini (come i diagrammi UML di Visio o i wireframe dell'interfaccia utente), così potrai anche avere pezzi visivi.

Come molte altre cose, penso che dovresti mirare a fare l'importo minimo che potrebbe funzionare. Non è la stessa cosa di nessuno però.

    
risposta data 02.02.2012 - 16:47
fonte
2

Non puoi sfuggire all'assegnazione del tempo per scrivere una documentazione adeguata. Equilibralo comunque a seconda di quanto lavoro ti viene dato, ma lascia un buon 15-20% del tuo tempo per documentare ciò che hai fatto. Tutti i membri del team devono essere coinvolti in questo, incluso il tuo manager, altrimenti ti documenterai solo a beneficio degli altri e non otterrai nulla in cambio. La documentazione deve essere parte integrante del tuo processo di sviluppo.

    
risposta data 02.02.2012 - 15:55
fonte
1

La documentazione dovrebbe dirvi PERCHÉ avete fatto qualcosa mentre lasciate la parte HOW al codice effettivo e la parte WHAT ai test delle unità. Qualcosa di più è un dolore. Questo di solito è abbastanza buono per le persone intelligenti che vogliono solo un punto di partenza.

Inoltre, non dimenticare di mantenere un'architettura di alto livello generale di ogni grande componente della tua base di codice. Rende molto facile indurre nuovi membri del team.

Infine, ogni volta che aggiungi una strana correzione, collega al tuo database di bug da un commento - molto utile.

    
risposta data 02.02.2012 - 18:03
fonte
1

Il tuo capo ha ragione non stampare alcuna documentazione UML che nessuno leggerà. Quello che facciamo nel nostro team è di navigare dal vivo nel modello usando le viste del diagramma di classe. Il principio è di aggiornare sempre MOF, il modello UML in diretta dal codice e lasciare che il diagramma di classe sia solo un visualizzatore del modello ma non il modello stesso.

Funziona molto bene perché tutta la complessità è fatta nel backoffice a livello di modello. Posso refactoring il mio progetto, scrivere java doc o scrivere uml documentazione nel modello. È una specie di click and go. Quando si fa clic si ottiene la documentazione live. Se qualcosa non è chiaro, apro il diagramma delle classi e inizio a giocarci. Elimina dai classificatori dei diagrammi, aggiungi nuovi classificatori, ingrandisci e riduci, mostra associazione, cancella associazione ecc ... Il modello non viene modificato perché non creo nuove informazioni sul modello, le uso solo.

È molto importante aprire il diagramma di un pacchetto ed essere in grado di leggere direttamente nel diagramma di classe un commento su cosa dovrebbe essere questa classe. Cosa dovrebbe fare questo metodo e qual è il flusso ecc ....

UML è fantastico, davvero utile, ma dovremmo smettere di usare Model Driven Devleopment per dare maggiore flessibilità e più iterazione alle fasi di modellazione / sviluppo. Il diagramma delle classi è aggiornato dal codice e la documentazione è sempre accurata e disponibile con un semplice clic. Non menzionerò uno strumento ma se usi Java ed Eclipse è facile trovare lo strumento che uso: -)

    
risposta data 03.02.2012 - 14:58
fonte

Leggi altre domande sui tag