Come posso documentare il lavoro passato di qualcun altro? [chiuso]

Penso che sia un esercizio inutile. Se funziona funziona, se non funziona, devi risolverlo.

Il modo migliore per documentare le cose vecchie è mentre ci lavori, documentare ciò che stai facendo e spiegare la logica di business (che presumo non sia stata documentata). Questo sarà di grande aiuto per qualsiasi nuovo sviluppatore.

Parlando di documentazione di vecchi codici / cose, qualcuno doveva possederlo. Supponiamo che questo sia il tuo attuale manager. Lui / lei potrebbe non avere una conoscenza tecnica completa di esso, ma saprà quali modifiche sono state apportate. In tal caso, non è il tuo lavoro. Potrebbe essere il gestore può scrivere qualcosa su di esso che modifiche sono state fatte. Sarebbe utile mantenere come storia. Se sorgono problemi come questo, puoi scavare in quelle aree, che potrebbero esserti di grande aiuto. Ma entrare nel codice e documentare le modifiche è IMO piuttosto inutile e probabilmente impossibile.

Abbandona i tuoi sforzi per documentare modifiche .

Inizia invece a documentare ciò che funziona attualmente e come . Conserva la documentazione aggiornata e aggiornata mentre apporti modifiche in futuro.

Hai il controllo del codice sorgente?

Riesci a capire cosa è cambiato da questo?

In tal caso, potresti essere in grado di associarlo alle modifiche aziendali, indipendentemente dalle nuove funzionalità o dai bug risolti.

È possibile resuscitare una vecchia cassetta postale per sviluppatori? (non sono sicuro se questo è fattibile con problemi di privacy o no). Potrebbero esserci molte informazioni da spulciare là.

Per prima cosa. Dove stai conservando la tua documentazione? Se non lo hai già fatto, configura una wiki. Preferisco dokuwiki me stesso, e c'è anche un prebuilt vm , se sei così inclinato.

Questo fornisce alcune caratteristiche importanti:

• È possibile accedere ai documenti ovunque nella lan dell'azienda (installazione sul nuovo computer ...)
• Tutti i documenti sono in un unico posto
• Tutti i documenti sono ricercabili
• Puoi collaborare (nuovo collega, utenti del software)

Ora, se la documentazione è in formato cartaceo, ti auguro il meglio. Se disponi di documenti di parole, crea uno script di importazione .

Finalmente, usa le cose . Ogni volta che devi installare qualcosa, inserisci delle note nel wiki. Se colpisci un caso limite, mettilo nella wiki. È qui che la collaborazione può brillare, dal momento che ottieni altre persone a fare il lavoro per te.

Passando a una documentazione più specifica, se hai bisogno di lavorare con il sorgente per vari progetti, assicurati di avere un ambiente di sviluppo adeguato impostato ! Per una lista di cose che dovresti avere:

• Controllo versione ( git , mercuriale , fossili )
• Monitoraggio dei bug ( trac , mantis , redmine , fossile )
• Sistema di build ( autotools , scons , buildbot )
• Controllo del progetto ( eclipse , struttura della directory specificata, plugin per l'editor )
• Documentazione sorgente (README, TODO, INSTALL, Commenti sorgente)

Infine, poiché la documentazione può essere noiosa, rendila un gioco. Datti "punti" per ogni oggetto nella tua lista di controllo, controllando periodicamente il tuo "punteggio". È un buon modo per vedere cosa hai realizzato e quanto bene. Indica anche dove devi andare dopo.

Considerare questa come un'opportunità per apprendere molte cose su come impostare un ambiente di sviluppo adeguato e non aver paura di provare le cose e andare avanti. Trova qualcosa che ti piace e migra l'ambiente in modo che le cose siano migliori . Approccia questo come un progetto in cui stai cercando di costruire la soluzione migliore.

Modifica

Come da commento del rig sotto, un'altra cosa utile da fare è creare diagrammi del codice sorgente. Freecode ha roba e questo article ne elenca alcuni per le lingue popolari.

Il meglio che puoi fare è documentare tutto ciò che sai e chiedere in giro alla compagnia di documentare tutto ciò che altri conoscono. Suggerisco di centralizzare la documentazione in un wiki o qualcosa di simile in modo che tutti possano accedere alla documentazione più aggiornata.

Non puoi documentare qualcosa che non conosci, quindi o tenti di imparare e scoprire perché qualcosa è stato fatto o lo lasci senza documenti. Questo è il motivo per cui la società deve prestare la massima cura per documentare le cose mentre quelli che ne sono a conoscenza sono ancora impiegati lì.

Se stai tentando di documentare qualsiasi codice che non capisci, ti suggerisco di scrivere test unitari per testare la funzionalità. In questo modo potrai capire meglio che cosa fa il codice e i test stessi possono servire da documentazione.

Buona fortuna!

Quando cerco di documentare qualcosa che qualcun altro che non fa più con il progetto o con la compagnia, inizio sempre l'atteggiamento di: questa è una blackbox per tutti, incluso me fino a quando ho bisogno di cambiare qualcosa o spiegarlo a qualcun altro .

Il motivo per cui questo progetto è nella forma della documentazione in cui lo hai trovato è perché la documentazione di qualsiasi lavoro è in qualche modo secondaria per farlo funzionare. Quindi documenta cosa cambi e se hai capito quale particolare campo nel database e quale particolare blocco di codice fa, se non per il beneficio altrui se non per il tuo.

Potresti scrivere test esplorativi automatizzati. Questi hanno diversi vantaggi:

• Scopri come funziona il sistema mentre li scrivi

• Servono come documentazione eseguibile per dopo

• Se li esegui su base regolare o addirittura continua, forniscono una bella rete di sicurezza per rilevare quando le modifiche rompono qualcosa o quando devono essere aggiornate

Non so se sia possibile scrivere quel tipo di test nel tuo ambiente particolare.