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

Siamo in una brutta situazione di avere pochissima documentazione sulla personalizzazione che i nostri ex lavoratori hanno fatto su un sistema aziendale critico. Numerose modifiche sono state apportate a Crystal Reports, entità di database e file proprietari di configurazione / programmazione per il nostro software ERP.

La documentazione corrente in genere legge qualcosa del genere:

Questo programma viene eseguito prima della fatturazione. Bug noti: nessuno.

Esegui questo programma dopo aver installato il software X.

Modificati i seguenti campi in questo rapporto: (senza alcuna spiegazione di come o perché)

Il nostro negozio IT è piccolo e, nel caso del software ERP, la maggior parte del lavoro è stata concentrata su una persona (che sono io ora), quindi nessun altro qui sa cosa abbiamo fatto. Il reparto IT e di contabilità conosce alcuni elementi (a volte abbastanza utili) ma non è sufficiente.

Un altro problema è che il nostro reparto contabilità sembra pensare che siamo ben documentati. È vero che abbiamo tenuto molti registri di ciò che è andato storto , ma molto poco spiega cosa (se non altro) è stato fatto per risolvere questi problemi. Abbiamo centinaia di articoli che spiegano i bug, ma i documenti che spiegano i cambiamenti (come mostrato sopra) sono quasi inutili.

Come posso documentare le modifiche passate quando non so cosa sia stato fatto? Posso iniziare con la documentazione di ciò che abbiamo cambiato: file, tabelle di database ecc. Che dobbiamo avere affinché il sistema funzioni. Posso anche documentare ciò che facciamo ; quando vengono eseguiti i report, perché alle persone è stato detto di utilizzare il report / programma X. Ma quando una di queste cose personalizzate ha un problema, torno sempre al punto di partenza.

Come posso documentare in modo proattivo queste cose per me e gli altri?

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

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

Parlando di documentare cose / codice vecchio, qualcuno doveva possederlo. Supponiamo che questo sia il tuo attuale manager. Potrebbe non averne una conoscenza tecnica completa, ma saprà quali modifiche sono state apportate. In tal caso, non è il tuo lavoro. Può essere il manager in grado di scrivere qualcosa a riguardo quali modifiche sono state apportate. Sarebbe utile conservare come storia. Se sorgono problemi del genere, puoi scavare in quelle aree, che potrebbero esserti molto utili. Ma entrare nel codice e documentare le modifiche è abbastanza inutile IMO e probabilmente impossibile.

Abbandona i tuoi sforzi per documentare le modifiche .

Invece, inizia a documentare ciò che funziona attualmente e come . Mantieni la documentazione aggiornata e aggiornata mentre apporti modifiche in futuro.

Hai il controllo del codice sorgente?

Riesci a capire cosa è cambiato da quello?

In tal caso, potresti essere in grado di associarlo alle modifiche aziendali, sia che si tratti di nuove funzionalità o correzioni di bug.

È possibile resuscitare una vecchia cassetta postale per sviluppatori? (non sono sicuro se questo è praticabile con problemi di privacy o meno). Potrebbero esserci molte informazioni da guadagnare attraverso la pesca a strascico.

Cominciando dall'inizio. Dove stai conservando la tua documentazione? Se non l'hai già fatto, imposta un wiki. Preferisco me stesso dokuwiki , e c'è anche una VM prefabbricata , se sei così incline.

Questo fornisce alcune importanti funzionalità:

• È possibile accedere ai documenti in qualsiasi punto della LAN aziendale (installazione su un 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 tua documentazione è in forma cartacea, ti auguro il meglio. Se hai documenti Word, crea uno script di importazione .

Infine, basta usare le cose . Ogni volta che è necessario installare qualcosa, inserire note nel wiki. Se colpisci un caso limite, inseriscilo nel wiki. Qui è dove può brillare la collaborazione, dal momento che altre persone fanno il lavoro per te.

Passando a una documentazione più specifica, se devi lavorare con la fonte per vari progetti, assicurati di avere un ambiente di sviluppo adeguato impostato ! Per un elenco di controllo delle cose dovresti avere:

• Controllo versione ( git , mercurial , fossil )
• Bug tracking ( trac , mantis , redmine , fossil )
• Sistema di compilazione ( autotools , scons , buildbot )
• Controllo del progetto ( eclissi , struttura di directory specificata, plug-in dell'editor )
• Documentazione di origine (README, TODO, INSTALL, Commenti di fonte)

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

Considerala come un'opportunità per imparare 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 . Approccio questo come un progetto in cui stai cercando di costruire la soluzione migliore.

Modificare:

Come da commento del rig di seguito, un'altra cosa utile da fare è creare diagrammi del codice sorgente. Freecode ha materiale e questo articolo ne elenca alcune per le lingue più diffuse.

Il meglio che puoi fare è documentare tutto ciò che sai e chiedere all'azienda di documentare tutto ciò che anche gli altri sanno. Suggerisco di centralizzare la documentazione in una wiki o qualcosa di simile in modo che tutti abbiano accesso alla documentazione più aggiornata.

Non puoi documentare qualcosa che non conosci, quindi o cerchi di imparare e scoprire perché qualcosa è stato fatto o lo lasci senza documenti. Questo è il motivo per cui la società deve prestare maggiore attenzione a documentare le cose mentre quelle che sanno sono ancora impiegate lì.

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

In bocca al lupo!

Quando provo a documentare qualcosa fatto da qualcun altro che non fa più parte del progetto o dell'azienda, inizio sempre l'atteggiamento di: questa è una scatola nera per tutti, incluso me, finché non 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 rispetto alla sua esecuzione. Quindi documenta cosa cambi e se hai capito cosa fa quel particolare campo nel database e quale particolare blocco di codice fa, se non per nessun altro vantaggio se non il tuo.

Potresti scrivere test esplorativi automatizzati. Questi hanno diversi vantaggi:

• Impara come funziona il sistema mentre li scrivi

• Servono come documentazione eseguibile per dopo

• Se li esegui su base regolare o persino continua, forniscono una buona 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 particolare ambiente.