Cosa dovresti lasciare alle spalle per i tuoi successori?

Supponi di essere un unico sviluppatore che lascia un lavoro. Che tipo di informazioni / materiale, al di fuori del codice stesso, dovresti creare e lasciare indietro per la tua sostituzione?

Una risposta ovvia è sicuramente "qualsiasi cosa tu voglia in un nuovo lavoro", ma è passato un po 'di tempo da quando ho iniziato un nuovo lavoro e ho dimenticato quali erano le cose più importanti di cui avevo bisogno in quel momento.

Sto pensando:

• account / password
• posizione delle apparecchiature, backup, CD del software

Cos'altro?

• Account e password
• Informazioni sul server
• Buon codice
• Documentazione
  • I diagrammi e le spiegazioni del database sono sorprendenti
  • Elenco delle stranezze nel codice
• procedure
• Spiegazione di processi manuali o lavori occasionali, non ovvi
• Elenco dei programmi che hanno usato o trovato utile
• Informazioni sui contatti ;)

Una forte tazza di caffè e una nota di scuse.

È quello che vorrei mi era rimasto.

• Documentazione. Quanto è difficile scrivere qualche commento? Creare note, note di distribuzione, spostare le note di sistema. Cosa fare quando si riavvia e tutto è andato.
• Papers. Scrivi perché è stato fatto in questo modo, quindi non devo chiedermi perché non lo stai facendo in un altro modo. Come funziona il sistema di backup, in che modo il server risponde a carichi, test, casi di test, casi d'uso.
• Appunti. "Quando si utilizza il database, non dirlo mai SELECT * FROM clients. Non siamo sicuri del perché ma scarica il database" .

Il mio indirizzo email, o forse anche il numero di telefono.

Nella mia esperienza è difficile annotare ogni dettaglio, quindi la cosa migliore è essere disponibile (in una certa misura) se i tuoi successori hanno bisogno di più informazioni.

Documentazione dei programmi che hai scritto, ad esempio il loro scopo, la posizione dei file sorgente per lo sviluppo futuro, le password, ecc.

Questo può essere all'interno del codice come commento o all'esterno in bella vista.

Più che una semplice documentazione, vorrei sapere perché determinate decisioni sono state prese quando sono state prese. Attualmente stiamo usando SWIG su un progetto e uno degli altri sviluppatori voleva sapere perché non abbiamo usato Boost :: Python. La semplice risposta è stata che il cliente al momento non consentiva l'uso di Boost. Adesso è una storia diversa.

Tali cose li aiuteranno non solo a comprendere il progetto, ma anche quali limiti / vincoli / sfide hanno superato la tua implementazione. Darà loro un punto di partenza per futuri interventi di manutenzione e potenziamento delle funzionalità.

Una cosa che non ho visto menzionare da chiunque (anche se avrei potuto trascurarlo) è documentare come impostare un ambiente di sviluppo. Mi rendo conto che la maggior parte delle volte è sufficiente installare alcune cose, ottenere le ultime novità, compilare e il gioco è fatto. Tuttavia a volte c'è molto di più (SharePoint è una situazione che viene in mente) e documentare quale condensatore di flusso deve essere configurato in modo che sarà molto utile per l'anima povera che ti segue.

Se si tratta di un programma desktop, come creare da zero l'intero sistema (possono essere diversi programmi separati), come creare un pacchetto per la distribuzione (quali dipendenze ha, ad esempio versioni di .NET) e come distribuirlo sui server per il download, se applicabile, o masterizzarlo su un CD o DVD.

Se si tratta di un programma basato sul Web, FTP e (se applicabile) accesso SSH al server e quali strumenti vengono utilizzati per creare e testare localmente il codice.

Se si tratta di un sistema incorporato, completare le istruzioni sulla creazione dell'immagine binaria, quali strumenti vengono utilizzati, come scaricare e eseguire il flashing del codice nel prodotto, come configurare il filesystem sul dispositivo, se presente.

Di recente ho lasciato un lavoro in circostanze simili a te (non ero l' unico sviluppatore, ma in realtà eravamo solo in due, quindi avevo molta conoscenza che l'altro non aveva (e viceversa, ovviamente)).

In termini di normale documentazione, è importante documentare una panoramica dell'intero sistema. I singoli componenti sono già documentati nel codice, ma l'interazione tra i componenti e perché ciò fa o perché questo deve parlare con quel componente sono importanti e non sempre facili da capire semplicemente eseguendo il debug / guardando il codice.

Quindi, per circa un mese prima di partire, ogni volta che facevo qualcosa che solo io potevo fare, scrivevo esattamente cosa era successo, cosa dovevo fare e perché. Questo di solito era un caso di "c'era un bug nel componente xyz, per risolverlo sapevo di cercare nel file abc a causa di X, quindi ho dovuto fare questo, questo e questo".

Ovviamente, ho lasciato il mio indirizzo e-mail e il mio numero di telefono nel caso fosse successo qualcosa che non potevano capire da soli. Ho ricevuto alcune chiamate nelle prime settimane, ma hanno lentamente abbandonato.

Vorremmo tutti un diagramma del flusso di dati completo del sistema con un elenco di requisiti funzionali. Molto probabilmente non l'hai mai capito quando hai scritto il sistema in primo luogo! Come la maggior parte dei luoghi, la migliore documentazione è probabilmente il codice stesso, quindi ciò che mi piacerebbe di più è un codice ben documentato. Righe e righe di commenti nel codice che spiegano cosa stai cercando di fare sia tecnicamente che funzionalmente.

La regola n. 1 per la documentazione non è ciò che fa ma perché . Qual è il retroscena dei programmi in esecuzione e cosa fanno?

Penso che ciò che mi piacerebbe vedere nelle documentazioni oltre al solito sarebbe ciò che le caratteristiche sono state lasciate fuori. Ad esempio, perché alcune idee NON sono state implementate o una determinata piattaforma o metodo NON utilizzato (che altrimenti sarebbe stata una scelta ovvia).

Questo si assicura che il successore sappia sempre cosa non fare o se è più capace, quindi forse può escogitare un lavoro e far funzionare alcune funzionalità.

Ciò è particolarmente applicabile ai progetti open source. Può risparmiare un sacco di tempo e potenza del cervello!