Wie schreibe ich eine technische Übergabedokumentation, bevor ich ein Unternehmen verlasse?

Sie schreiben eine sogenannte „Übergabedokumentation“. Das Ziel dieser Dokumentation ist es, Wissen darüber, wie diese Software funktioniert und wie sie geschrieben, gewartet und bereitgestellt wird, an Personen weiterzugeben, die Ihnen folgen werden.

Es gibt eine verwandte Frage/Antwort auf Stack Overflow, die im Allgemeinen die Themen abdeckt, die Sie in Ihrem eigenen Dokument ansprechen müssen:

Welche Kernelemente müssen in die Support-Dokumentation aufgenommen werden?

Auszugsweise zitiert:

• Die Dokumentation des Codes (Javadoc, Doxygen usw.)
• Details zum Build-Prozess
• Wo man die aktuellen Quellen erhält
• Wie Fehler gemeldet werden (sie werden auftreten)
• Route zur Bereitstellung von Patches entweder an die Quelle oder an Kunden

• Wie es funktioniert (einfach, aber oft übersehen)
• Vom Benutzer anpassbare Teile (z. B. gibt es eine Skriptkomponente)
• Hauptkontakte für jede Komponente, auch bekannt als Eskalationspfad
• Ermutigung für Feedback vom Support, was sie sonst noch sehen möchten

Bedenken Sie auch:

• System-/Benutzeranmeldeinformationen erforderlich (geben Sie die Passwörter nicht in die Dokumentation ein!)
• Wo sich die dev/test/UAT/database/alle anderen zugeordneten Server befinden
• Wo sich der Produktionsserver befindet
• Bereitstellungsschritte
• Ob Lizenzen involviert sind
• Ort der ursprünglichen Anforderungen/Analysedokumente für jede Arbeit

Wenn Sie "Übergabedokumentation" googeln, erhalten Sie auch weitere Einblicke.

Um Zeit zu sparen, würde ich eine Reihe von Stichpunkten aufschreiben (wie oben und aus Ihrer eigenen Recherche zu diesem Projekt) und sie Ihrem PM präsentieren. Bitten Sie ihn, diejenigen anzukreuzen, die er sehen möchte, und andere hinzuzufügen, die er für angemessen hält.

Ich werde eine etwas zynische, des Teufels Advokaten-Ansicht einnehmen ...

Die Antwort von Snow listet eine ganze Menge guter Dinge auf, die dokumentiert werden sollten, aber fast alles davon sollte bereits dokumentiert sein und ständig auf dem neuesten Stand gehalten werden. Wenn diese Dokumentation nicht existiert (und ich weiß, dass es viele Stellen gibt, wo sie nicht existiert), dann ist das im Wesentlichen ein Versagen Ihres Managements, das während Ihrer Zeit im Unternehmen nicht die richtigen Praktiken eingeführt hat. Wenn dies der Fall ist, ist es nicht gut, wenn sie versuchen, ihr Versagen zu beheben, indem sie die Person „abladen“, die die Verantwortung für „alles Dokumentieren“ überlässt.

Kilisis Antwort schlägt vor: " Mach es so, wie du es lesen möchtest, wenn du übernehmen würdest ", was wiederum ein schönes Ideal ist, aber vielleicht mit der Berücksichtigung dessen, was du am ersten Tag erhalten hast, gemildert werden sollte. Wenn Ihnen so gut wie nichts gegeben wurde, z. B.: " Da ist der Code, wenn Sie nicht herausfinden können, wie etwas funktioniert, fragen Sie jemanden ", und die Situation hat sich nicht geändert, seit Sie angefangen haben, ist es wieder nicht wirklich die Verantwortung der Person, die das Unternehmen verlässt, um schlechte Praktiken zu beheben.

Der Kern dessen, was ich zu sagen versuche, ist: Wenn es zutrifft, lassen Sie sich nicht dazu drängen, von Natur aus schlechte Praktiken zu beheben .

• Wenn die meisten Dinge bereits ausführlich dokumentiert sind, sollte Ihre "Übergabe" relativ kurz sein; die Handvoll Dinge "in deinem Kopf", die anderen vielleicht nicht ganz bewusst sind. Sie wissen am besten, was diese sind, sollten sich jedoch von Ihrem Projektmanager zu bestimmten Bereichen beraten lassen, an denen sie interessiert sind.

• Wenn die vorhandene Dokumentation spärlich, veraltet oder nicht vorhanden ist, liegt es nicht in Ihrer Verantwortung, „systembedingte Fehler“ zu beheben, wenn Sie das Unternehmen verlassen. Überlegen Sie, was Sie können, um dem armen Kerl zu helfen, der Sie ersetzt, aber fühlen Sie sich nicht schuldig, denn diese Situation hätte (vom Management) schon vor langer Zeit angegangen werden sollen.

Wenn Sie absichtlich Informationen „gehortet“ haben, die nur Sie kennen, und die vorhandene Dokumentation nicht auf dem neuesten Stand gehalten haben, dann sollte es natürlich in Ihrer Verantwortung liegen, diese Informationen endlich so hilfreich wie möglich weiterzugeben !

Wie sollte mein Ansatz dazu aussehen?

Machen Sie es so, wie Sie es lesen möchten, wenn Sie übernehmen würden. Abgesehen davon, kündigen Sie einfach und konzentrieren Sie sich darauf, wohin Ihre Karriere geht. Wenn Ihr Chef Ihnen kein Format gibt, dem Sie folgen können, können Sie nicht viel anderes tun, mit dem er/sie vollkommen zufrieden sein wird.

Normalerweise mache ich eine Schritt-für-Schritt-Anleitung aller meiner Aufgaben, vorausgesetzt, sie muss von einem Anfänger befolgt werden. Also keine Abkürzungen, kein Slang etc.

Das Wichtigste, was ich wissen möchte, wenn ich von einem anderen Entwickler übernehme, ist das gemeinsame „Was, Warum, Wie“ des Projekts. Das ist:

• Was ist es? Was tut es?

• Warum haben Sie sich entschieden, die Dinge auf eine bestimmte Art und Weise zu tun? Ich werde mich immer fragen, warum sich ein Entwickler für ein bestimmtes Framework oder eine bestimmte Sprache entschieden hat und Kontext oder Warnungen vor bestimmten Dingen, die ich nicht berücksichtigt hatte, von unschätzbarem Wert sind.

• Wie löst das Projekt die aufgeführten Probleme?

Das andere Wichtigste ist, eine neue Maschine zu bekommen, die nichts mit dem Projekt zu tun hat, und zu versuchen, ein funktionierendes Setup darauf zu bekommen (genau wie sie es tun müssen, wenn sie übernehmen).

Sie haben keine Ahnung, wie oft ich einen Ex-Projektentwickler gefragt habe, warum seine Dokumentation nicht funktioniert hat, und er sagte: „Oooh, ja, Sie müssen nur diese Umgebungsvariable hinzufügen, das hatte ich vergessen.“ Es ist normal und menschlich, nicht jeden Schritt einer Installation zu notieren, aber es wird dem nächsten Entwickler das Leben so viel einfacher machen, vorausgesetzt, Sie sind jetzt in der richtigen Einstellung.

Stellen Sie sich vor, Sie führen einen Wissenstransfer mit einem anderen Entwickler durch, der dort weitermacht, wo Sie aufgehört haben. Normalerweise gehen Sie den Code auf hoher Ebene durch und erwähnen alles, was Sie interessiert, besondere Schmerzpunkte, Orte, an denen häufig Fehler auftreten usw. Dies gibt Ihnen Ausgangspunkte für die Erstellung der Dokumentation.

Da dies ein schriftliches Dokument ist und der nächste Mitarbeiter keine Fragen stellen kann, möchten Sie vielleicht deutlicher sein als bei einer mündlichen Übersicht.

Arbeitet die Person, die Ihre Aufgaben übernimmt, bereits für das Unternehmen oder wird es zu Überschneidungen mit Ihnen kommen?

Wenn ja, lassen Sie diese Person die Dokumentation überprüfen, wenn sie für sie gut genug ist. (Oder wenn Sie einen Kollegen haben, der Ihnen helfen kann.) Es ist unmöglich, alles abzudecken, also konzentrieren Sie sich auf die schwierigen Dinge, die seltsamen Dinge, die Ausnahmen von Industriestandards und so weiter.

Und ich weiß, dass es langweilig ist und du wahrscheinlich gedanklich schon die Firma verlassen hast. Und je nachdem warum man dem Unternehmen mehr oder weniger die Treue gelassen hat. Aber ich schlage vor, iterativ zu arbeiten, damit Sie kürzere Ziele haben und häufig Feedback einholen. Da Sie nur noch wenig Zeit haben und das Unternehmen Sie so effizient wie möglich einsetzen sollte, ist das Schreiben unnötiger Dokumentation eine Verschwendung, und wichtige Dinge werden möglicherweise verpasst.