Was sollten Sie für Ihre Nachfolger hinterlassen?

Angenommen, Sie sind ein einziger Entwickler, der einen Job verlässt. Welche Art von Informationen / Material sollten Sie außerhalb des Codes selbst erstellen und für Ihre Ersetzung zurücklassen?

Eine offensichtliche Antwort ist "was auch immer Sie sich für einen neuen Job wünschen", aber es ist schon eine Weile her, dass ich einen neuen Job angefangen habe, und ich vergesse, was die wichtigsten Dinge waren, die ich damals brauchte.

Ich denke:

• Konten / Passwörter
• Ort der Ausrüstung, Backups, Software-CDs

Was sonst?

• Konten und Passwörter
• Serverinformation
• Guter Code
• Dokumentation
  • Datenbankdiagramme und Erklärungen sind erstaunlich
  • Liste der Seltsamkeiten im Code
• Verfahren
• Erklärung manueller Prozesse oder gelegentlicher, nicht offensichtlicher Arbeiten
• Liste der Programme, die sie verwendet haben oder die sie hilfreich fanden
• Kontakt Informationen ;)

Eine starke Tasse Kaffee und eine Entschuldigung.

Ist das, was ich wünschte, ich wäre verlassen.

• Dokumentation. Wie schwer ist es, ein paar Kommentare zu schreiben? Erstellen Sie Notizen, Bereitstellungsnotizen und verschieben Sie die Systemnotizen. Was ist zu tun, wenn Sie neu starten und alles weg ist?
• Papiere. Schreiben Sie auf, warum es so gemacht wird, damit ich mich nicht wundern muss, warum Sie es nicht anders machen. Wie funktioniert das Backup-System, wie reagiert der Server auf Lasten, Tests, Testfälle und Anwendungsfälle?
• Anmerkungen. „Wenn die Datenbank mit, sagen Sie nicht immer SELECT * FROM clients. Wir sind nicht sicher, warum , aber es die Datenbank - Dumps“ .

Meine E-Mail-Adresse oder vielleicht sogar Telefonnummer.

Meiner Erfahrung nach ist es schwierig, jedes Detail aufzuschreiben. Daher ist es das Beste, (bis zu einem gewissen Grad) verfügbar zu sein, wenn Ihre Nachfolger weitere Informationen benötigen.

Dokumentation der von Ihnen geschriebenen Programme, z. B. Zweck, Speicherort der Quelldateien für die zukünftige Entwicklung, Passwörter usw.

Dies kann entweder innerhalb des Codes als Kommentar oder außerhalb in Sichtweite sein.

Ich möchte nicht nur die Dokumentation kennen lernen, sondern auch, warum bestimmte Entscheidungen getroffen wurden, als sie getroffen wurden. Wir verwenden SWIG derzeit in einem Projekt und einer der anderen Entwickler wollte wissen, warum wir Boost :: Python nicht verwendet haben. Die einfache Antwort war, dass der Kunde die Verwendung von Boost zu diesem Zeitpunkt nicht zugelassen hatte. Jetzt ist eine andere Geschichte.

Solche Dinge werden ihnen nicht nur dabei helfen, das Projekt zu verstehen, sondern auch, welche Einschränkungen / Einschränkungen / Herausforderungen Ihre Implementierung bewältigt hat. Sie erhalten einen Ausgangspunkt für zukünftige Wartungs- und Funktionserweiterungen.

Eine Sache, die ich nicht erwähnt habe (obwohl ich sie vielleicht übersehen habe), ist zu dokumentieren, wie eine Entwicklungsumgebung eingerichtet wird. Mir ist klar, dass es die meiste Zeit nur darum geht, ein paar Dinge zu installieren, auf den neuesten Stand zu bringen, zu kompilieren und fertig zu sein. Manchmal steckt jedoch noch mehr dahinter (SharePoint ist eine der denkbaren Situationen). Wenn Sie dokumentieren, welcher Flusskondensator auf welche Weise konfiguriert werden muss, ist dies für die arme Seele, die Ihnen folgt, sehr hilfreich.

Wenn es sich um ein Desktop-Programm handelt, wie Sie das gesamte System von Grund auf neu erstellen (möglicherweise mehrere separate Programme), wie Sie ein Paket für die Verteilung erstellen (welche Abhängigkeiten es hat, z. B. .NET-Versionen) und wie Sie es auf Servern bereitstellen Zum Herunterladen, falls zutreffend, oder zum Brennen auf eine CD oder DVD.

Wenn es sich um ein webbasiertes Programm handelt, FTP- und (falls zutreffend) SSH-Zugriff auf den Server und welche Tools zum lokalen Erstellen und Testen des Codes verwendet werden.

Wenn es sich um ein eingebettetes System handelt, befolgen Sie die Anweisungen zum Erstellen des Binärabbilds, zu den verwendeten Tools, zum Herunterladen und Flashen des Codes in das Produkt sowie zum Einrichten des Dateisystems auf dem Gerät (sofern vorhanden).

Ich habe kürzlich einen Job unter ähnlichen Umständen wie Sie verlassen (ich war nicht der einzige Entwickler, aber es waren wirklich nur zwei von uns, also hatte ich ziemlich viel Wissen, das der andere Kerl nicht hatte (und umgekehrt). Na sicher)).

Im Sinne der normalen Dokumentation ist es wichtig, einen Überblick über das gesamte System zu dokumentieren. Einzelne Komponenten sind bereits im Code dokumentiert, aber die Interaktion zwischen Komponenten und warum dies so ist oder warum dies mit dieser Komponente gesprochen werden muss, ist wichtig und nicht immer einfach durch einfaches Debuggen / Betrachten des Codes herauszufinden.

Dann schrieb ich ungefähr einen Monat lang, bevor ich ging, jedes Mal, wenn ich etwas tat, was nur ich tun konnte , genau auf, was passiert war, was ich tun musste und warum. Dies war normalerweise ein Fall von "Es gab einen Fehler in der XYZ-Komponente, um ihn zu beheben, wusste ich, dass ich wegen X in der Datei abc suchen musste, dann musste ich dies, dies und das tun".

Natürlich habe ich meine E-Mail-Adresse und Telefonnummer hinterlassen, falls etwas auftauchte, das sie nicht selbst herausfinden konnten. Ich habe in den ersten Wochen ein paar Anrufe bekommen, die aber langsam abbrachen.

Wir möchten alle ein vollständiges Datenflussdiagramm des Systems mit einer Liste der funktionalen Anforderungen. Höchstwahrscheinlich haben Sie das nie bekommen, als Sie das System überhaupt geschrieben haben! Wie die meisten Orte ist die beste Dokumentation wahrscheinlich der Code selbst. Was ich am liebsten hätte, ist gut dokumentierter Code. Zeilen und Kommentarzeilen im Code erläutern, was Sie technisch und funktional tun möchten.

Die Hauptregel für die Dokumentation ist nicht, was es tut, sondern warum . Was ist die Hintergrundgeschichte der ausgeführten Programme und was tun sie?

Ich denke, was ich in Dokumentationen neben dem Üblichen gerne sehen würde, wäre, welche Funktionen weggelassen wurden. Zum Beispiel, warum bestimmte Ideen NICHT implementiert wurden oder eine bestimmte Plattform oder Methode NICHT verwendet wurde (was ansonsten eine naheliegende Wahl war).

Auf diese Weise wird sichergestellt, dass der Nachfolger immer weiß, was er nicht tun soll, oder dass er, wenn er besser in der Lage ist, eine Lösung finden und bestimmte Funktionen zum Laufen bringen kann.

Dies gilt insbesondere für Open Source-Projekte. Kann viel Zeit und Gehirnleistung sparen!