Wie kann ich die früheren Arbeiten anderer dokumentieren? [geschlossen]

Wir sind in einer schlechten Situation, weil wir nur sehr wenige Unterlagen zur Anpassung unserer früheren Mitarbeiter an ein geschäftskritisches System haben. Viele Änderungen wurden an Crystal Reports, Datenbankeinheiten und proprietären Konfigurations- / Programmierdateien für unsere ERP-Software vorgenommen.

Die aktuelle Dokumentation lautet im Allgemeinen ungefähr so:

Dieses Programm wird vor der Rechnungsstellung ausgeführt. Bekannte Fehler: keine.

Führen Sie dieses Programm nach der Installation von Software X aus.

Die folgenden Felder in diesem Bericht wurden geändert: (ohne Erklärung, wie oder warum)

Unser IT-Shop ist klein, und im Fall der ERP-Software wurde die meiste Arbeit auf eine Person konzentriert (das bin ich jetzt), sodass hier niemand weiß, was wir alles getan haben. Die IT- und Buchhaltungsabteilung kennt sich aus (gelegentlich recht hilfreiche), aber das reicht nicht aus.

Ein weiteres Problem ist, dass unsere Buchhaltungsabteilung zu glauben scheint, dass wir gut dokumentiert sind. Es ist wahr, dass wir viele Aufzeichnungen darüber geführt haben, was schief gelaufen ist , aber nur sehr wenig erklärt, was (wenn überhaupt) getan wurde, um diese Probleme zu beheben. Wir haben Hunderte von Artikeln, in denen Fehler erklärt werden, aber die Dokumente, in denen Änderungen erklärt werden (wie oben gezeigt), sind fast nutzlos.

Wie kann ich frühere Änderungen dokumentieren, wenn ich nicht weiß, was alles getan wurde? Ich kann damit beginnen, zu dokumentieren, was wir geändert haben: Dateien, Datenbanktabellen usw., die wir benötigen, damit das System funktioniert. Ich kann auch dokumentieren, was wir tun . Wenn Berichte ausgeführt werden, warum wurde den Benutzern gesagt, dass sie X-Bericht / Programm verwenden sollen. Aber wenn eines dieser maßgeschneiderten Dinge ein Problem hat, bin ich immer wieder auf dem ersten Platz.

Wie kann ich dieses Zeug proaktiv für mich und andere dokumentieren?

Ich denke, das ist eine sinnlose Übung. Wenn es funktioniert, funktioniert es, wenn es nicht funktioniert, müssen Sie es beheben.

Der beste Weg, um alte Dinge zu dokumentieren, besteht darin, während Sie daran arbeiten, zu dokumentieren, was Sie tun, und die Geschäftslogik zu erklären (von der ich annehme, dass sie nicht dokumentiert wurde). Dies ist eine große Hilfe für jeden neuen Entwickler.

Apropos alten Code / Dinge zu dokumentieren, jemand musste ihn besitzen. Nehmen wir an, dies ist Ihr aktueller Manager. Er / sie verfügt möglicherweise nicht über vollständige technische Kenntnisse, weiß jedoch, welche Änderungen vorgenommen wurden. In diesem Fall ist es nicht Ihre Aufgabe. Möglicherweise kann der Manager etwas darüber schreiben, welche Änderungen vorgenommen wurden. Das wäre hilfreich, um als Geschichte zu behalten. Wenn ein solches Problem auftritt, können Sie in diese Bereiche graben, was für Sie sehr hilfreich sein kann. Aber in den Code zu gehen und die Änderungen zu dokumentieren, ist IMO ziemlich nutzlos und wahrscheinlich unmöglich.

Geben Sie Ihre Bemühungen auf, Änderungen zu dokumentieren .

Beginnen Sie stattdessen damit, zu dokumentieren, was aktuell funktioniert und wie . Halten Sie diese Dokumentation auf dem neuesten Stand und aktuell, wenn Sie in Zukunft Änderungen vornehmen.

Haben Sie Quellcodeverwaltung?

Können Sie herausfinden, was sich daran geändert hat?

Wenn ja, können Sie dies möglicherweise geschäftlichen Änderungen zuordnen, unabhängig davon, ob es sich um neue Funktionen oder Fehlerbehebungen handelt.

Ist es möglich, ein altes Entwicklerpostfach wiederzubeleben? (nicht sicher, ob dies mit Datenschutzbedenken möglich ist oder nicht). Es kann viele Informationen geben, die durch das Durchsuchen dort gewonnen werden können.

Das wichtigste zuerst. Wo speichern Sie Ihre Dokumentation? Wenn Sie es noch nicht getan haben, richten Sie ein Wiki ein. Ich bevorzuge Dokuwiki selbst und es gibt sogar eine vorgefertigte VM , wenn Sie so geneigt sind.

Dies bietet einige wichtige Funktionen:

• Auf Dokumente kann überall im Unternehmensbereich zugegriffen werden (Installation auf einem neuen Computer ...)
• Alle Dokumente befinden sich an einem Ort
• Alle Dokumente sind durchsuchbar
• Sie können zusammenarbeiten (neuer Kollege, Benutzer der Software)

Wenn Ihre Dokumentation in Papierform vorliegt, wünsche ich Ihnen alles Gute. Wenn Sie Word-Dokumente haben, erstellen Sie ein Importskript .

Zum Schluss einfach das Zeug benutzen . Wenn Sie etwas installieren müssen, fügen Sie Notizen in das Wiki ein. Wenn Sie auf einen Randfall stoßen, fügen Sie ihn in das Wiki ein. Hier kann die Zusammenarbeit glänzen, da Sie andere Leute dazu bringen, die Arbeit für Sie zu erledigen.

Wenn Sie mit der Quelle für verschiedene Projekte arbeiten müssen, stellen Sie sicher, dass Sie eine geeignete Entwicklungsumgebung eingerichtet haben ! Für eine Checkliste mit Dingen, die Sie haben sollten:

• Versionskontrolle ( Git , Quecksilber , Fossil )
• Bug Tracking ( Trac , Mantis , Redmine , Fossil )
• Build-System ( Autotools , Scons , Buildbot )
• Projektsteuerung ( Eclipse , angegebene Verzeichnisstruktur, Editor-Plugin )
• Quelldokumentation (README, TODO, INSTALL, Quellkommentare)

Schließlich, weil Dokumentation langweilig sein kann, machen Sie es zu einem Spiel. Geben Sie sich "Punkte" für jeden Punkt in Ihrer Checkliste und überprüfen Sie regelmäßig Ihre "Punktzahl". Auf diese Weise können Sie sehen, was Sie erreicht haben und wie gut. Außerdem wird festgelegt, wohin Sie als Nächstes gehen müssen.

Betrachten Sie dies als Gelegenheit, viele Dinge über das Einrichten einer richtigen Entwicklungsumgebung zu lernen, und haben Sie keine Angst, Dinge auszuprobieren und weiterzumachen. Finden Sie etwas, das Ihnen gefällt, und migrieren Sie die Umgebung, damit die Dinge besser werden . Betrachten Sie dies als ein Projekt, bei dem Sie die beste Lösung entwickeln möchten.

Bearbeiten:

Gemäß dem Kommentar des Rigs unten ist es auch nützlich, Diagramme des Quellcodes zu erstellen. Freecode hat Sachen , und dieser Artikel listet einige für beliebte Sprachen auf.

Das Beste, was Sie tun können, ist, alles zu dokumentieren, was Sie wissen, und im Unternehmen zu bitten, alles zu dokumentieren, was auch andere wissen. Ich schlage vor, die Dokumentation in einem Wiki oder ähnlichem zu zentralisieren, damit jeder Zugriff auf die aktuellste Dokumentation hat.

Sie können etwas, das Sie nicht kennen, nicht dokumentieren. Entweder versuchen Sie zu lernen und herauszufinden, warum etwas getan wurde, oder Sie lassen es einfach undokumentiert. Aus diesem Grund muss das Unternehmen bei der Dokumentation der Dinge größere Sorgfalt walten lassen, während diejenigen, die es wissen, noch dort beschäftigt sind.

Wenn Sie versuchen, Code zu dokumentieren, den Sie nicht verstehen, empfehlen wir Ihnen, Komponententests zu schreiben, um die Funktionalität zu testen. Auf diese Weise verstehen Sie besser, was der Code tut, und die Tests selbst können als Dokumentation dienen.

Viel Glück!

Wenn ich versuche, etwas zu dokumentieren, das jemand anderes, der nicht mehr im Projekt oder im Unternehmen ist, getan hat, beginne ich immer mit der Einstellung: Dies ist eine Blackbox für alle, einschließlich mir, bis ich etwas ändern oder jemand anderem erklären muss.

Der Grund dafür, dass dieses Projekt die Dokumentationsform hat, in der Sie es gefunden haben, liegt darin, dass die Dokumentation von Arbeiten etwas zweitrangig ist, um sie zum Laufen zu bringen. Dokumentieren Sie also, was Sie ändern und ob Sie herausgefunden haben, was das jeweilige Feld in der Datenbank und welcher bestimmte Codeblock bewirkt, wenn dies nur für Sie von Vorteil ist.

Sie könnten automatisierte Erkundungstests schreiben. Diese haben mehrere Vorteile:

• Sie lernen, wie das System funktioniert, während Sie sie schreiben

• Sie dienen als ausführbare Dokumentation für später

• Wenn Sie sie regelmäßig oder sogar kontinuierlich ausführen, bieten sie ein nützliches Sicherheitsnetz, um zu erkennen, wann Änderungen etwas beschädigen oder wann sie aktualisiert werden müssen

Ich weiß jedoch nicht, ob es möglich ist, solche Tests in Ihrer speziellen Umgebung zu schreiben.