Wie dokumentiere ich ein bereits entwickeltes Projekt?

Ich würde gerne wissen, welche Optionen zur Dokumentation eines bereits entwickelten Projekts zur Verfügung stehen, da die Entwickler, die daran gearbeitet haben, nicht einmal eine einzige Dokumentationsseite geschrieben haben.

Das Projekt enthält keine anderen Details als viele Seiten mit Skripten mit Funktionen, die von Entwicklern geschrieben und geändert wurden, die in den letzten zwei Jahren an diesem Projekt gearbeitet haben. Ich habe nur das Datenbankschema und die Projektdateien. Ich würde gerne wissen, ob es eine Möglichkeit gibt, dieses Projekt zu organisieren und zu dokumentieren, damit es für die Entwickler hilfreich sein kann, die in Zukunft an diesem Projekt arbeiten werden.

Das Projekt wurde mit PHP und MySQL entwickelt. Die Funktionen sind schlecht kommentiert, so dass ich keine guten Ergebnisse erzielen kann, wenn ich sie mit Sauerstoff ausführe.

Wer liest die Dokumentation? Wofür wird die Dokumentation verwendet? Dies sind die wichtigsten zu beantwortenden Fragen. Beispielsweise würde sich die Dokumentation für Wartungsentwickler mehr auf die Struktur konzentrieren, während sich die Dokumentation für Entwickler, die in das Produkt integriert sind, mehr auf Webdienste und die Datenbankstruktur konzentrieren würde.

Machen Sie im Allgemeinen so viel Dokumentation wie erforderlich und nicht mehr. Viele Organisationen benötigen Dokumentation, weil jemand darauf bestand, dass dies eine bewährte Methode ist, aber die Dokumentation verstaubt.

Angenommen, die Benutzer verwenden die Dokumentation tatsächlich, versuchen Sie nicht, den Code und die Datenbank auf der kleinsten Ebene zu erfassen. Entwickler werden sich den Code für Minutien ansehen. Konzentrieren Sie sich stattdessen auf Details, die im Code nicht ersichtlich sind , z. B.:

1. Die Anwendungsfälle, denen das Produkt entspricht. Dies kann angesichts des Alters des Produkts schwierig sein, aber die Erfassung der Funktionen des Produkts bietet nicht-technischen Lesern und Testern einen wichtigen Kontext. Wer sind die Wettbewerber auf dem Markt (falls vorhanden)? Gibt es etwas, das vom Produktumfang ausgeschlossen ist?
2. Alle eindeutigen nicht funktionalen Anforderungen . Wurde das Produkt beispielsweise für ein bestimmtes Volumen geschrieben? Wie alt können die Daten sein? Wo wird Caching verwendet? Wie werden Benutzer authentifiziert? Wie funktioniert die Zugangskontrolle?
3. Ein Kontextdiagramm, das die Interaktion mit anderen Systemen wie Datenbank, Authentifizierungsquellen, Sicherung, Überwachung usw. zeigt.
4. (Falls bekannt) Risiken und wie sie zusammen mit einem Entscheidungsregister gemindert wurden . Dies ist im Nachhinein wahrscheinlich schwierig, aber es gibt oft kritische Entscheidungen, die ein Design beeinflussen. Erfassen Sie alles, was Sie kennen.
5. Gemeinsame Entwurfsmuster oder Entwurfsrichtlinien . Gibt es beispielsweise eine Standardmethode für den Zugriff auf die Datenbank? Gibt es einen Kodierungs- oder Namensstandard?
6. Kritische Codepfade , normalerweise unter Verwendung von Flussdiagrammen oder UML-Aktivitäts- oder Sequenzdiagrammen. Es gibt möglicherweise keine im Projekt, aber dies sind normalerweise diejenigen, die Geschäftsbenutzer artikuliert haben.

Auch wenn nicht alle diese Informationen verfügbar sind, starten Sie jetzt . Die Entwickler, die nach Ihnen kommen, werden es Ihnen danken.

Gute automatisierte Komponententests oder Testfälle können ebenfalls eine nützliche Dokumentation sein, obwohl sie für weniger technische Personen schwer zugänglich sind.

Es hört sich auch so an, als müssten Sie eine kulturelle Veränderung vornehmen , um Dokumentation aufzunehmen . Fangen Sie klein an, aber im Idealfall sollte das Projekt erst dann "abgeschlossen" werden, wenn mindestens ein Mindestmaß an Dokumentation vorhanden ist. Dies ist wahrscheinlich der schwierigste Schritt, da Sie die oben genannten Dinge steuern können. Darauf müssen sich andere einlassen. Es kann jedoch auch am lohnendsten sein, insbesondere wenn das nächste Projekt, das Sie durchführen, eine gute Dokumentation enthält.

In der Vergangenheit habe ich eine solche Situation bewältigt, indem ich mich mit den verschiedenen Produktbesitzern oder Hauptbenutzern zusammengesetzt, ihre primären Anwendungsfälle durchgesehen und diese mit einer Reihe von Tests dokumentiert habe. Sie können diese als Basis für das System verwenden, wenn Sie in Zukunft Änderungen vornehmen. Dies kann auch dazu beitragen, Bereiche des Systems zu identifizieren, die keinen Eigentümer oder Anwendungsfall haben und möglicherweise gelöscht werden.

Es hängt alles wirklich von der Größe des Systems ab. Wenn es sich um ein komplexes System mit vielen verschiedenen Stakeholdern handelt, können Sie ein übergeordnetes Komponentendiagramm erstellen, in dem angegeben ist, welche Funktionen vorhanden sind und wo sie zufrieden sind. Dies kann sehr hilfreich sein, um Architekturprobleme im Systemdesign zu identifizieren.

Im Allgemeinen empfehle ich, altmodische Dokumentationen zu vermeiden, da diese veraltet sind und Entwickler in Zukunft nicht mehr führen können. Ich versuche immer, lebende Dokumentationen in Form von Tests zu erstellen, die während der Entwicklung des Systems beibehalten werden.

Das Wichtigste zuerst, wer ist Ihre Zielgruppe? Zukünftige Entwickler oder andere Geschäftsleute? Mit Blick auf die Antwort auf diese Frage:

Wie andere gesagt haben, ist eine Beschreibung auf hoher Ebene das erste, was Sie brauchen. Erklären Sie, was das System im breiteren Schema der Dinge zu tun versucht. Erklären Sie, worauf es läuft, wie es in das Netzwerk passt und mit jedem anderen System kommuniziert. Dann ging ich jeden Bildschirm durch, machte einen Screenshot und gab eine kurze Erklärung, was der Bildschirm tut und wie er mit anderen Teilen des Systems interagiert. Wenn es für Entwickler ist, halten Sie es im Gespräch, als würden Sie ihnen die App zum ersten Mal erklären. Immerhin ist das der Punkt des Dokuments (nehme ich an).

Für jede komplizierte Verarbeitung oder Logik würde ich ein Zustandsdiagramm, ein Datenflussdiagramm oder ein Sequenzdiagramm verwenden. Machen Sie auf jeden Fall ein Entitätsdiagramm und dann ein DB-Schema-Design (zwei verschiedene Dinge!). Vielleicht ein grundlegendes Klassendiagramm, aber halten Sie es einfach. Beachten Sie nur die wichtigsten Dinge, die von Interesse sind. Entwickler können diese Dinge herausfinden, indem sie sich den Code ansehen.

Wenn Sie Probleme beim Einstieg haben, tun Sie einfach so, als wäre direkt neben Ihnen ein anderer Entwickler im Raum, der nicht das Erste über das System weiß. Ich bin relativ ungeduldig und muss nur das Wesentliche wissen. Dann fang an zu erklären und schreibe auf, was du sagst :)

Die vorherigen Vorschläge sind alle gut, aber ich würde auch in Betracht ziehen, zu untersuchen, ob Ihre Benutzergemeinschaft selbst Ad-hoc-Dokumentationen erstellt hat. In Ihrer Frage wurde nicht angegeben, ob jemals eine Version Ihres "Produkts" (seit zwei Jahren vorhanden) für Benutzer freigegeben wurde. Wenn es verwendet wurde und keine offizielle Dokumentation vorhanden ist, war entweder keine Dokumentation erforderlich, oder es gibt eine inoffizielle Dokumentation, die möglicherweise rudimentär ist, aber von den Benutzern wahrscheinlich auch als wesentlich angesehen wird. Durchsuchen Sie das Web nach Artefakten, die möglicherweise kritische APIs darstellen, suchen Sie in Foren, fragen Sie Power-User und suchen Sie nach Fragen- und Antwortseiten. Versuchen Sie nach Möglichkeit, eine Dokumentation zu schreiben, die einen technischen oder geschäftlichen Bedarf erfüllt.

Die Frage ist, möchten Sie es so dokumentieren, wie es jetzt ist oder wie es sein sollte?

Was ich aus Ihrer Frage gelesen habe, ist, dass Sie über API-Dokumentation und nicht so viel Benutzerdokumentation nachdenken und der Code möglicherweise nicht so gut gepflegt und kryptisch ist.

Ich fürchte, wenn Sie jetzt dokumentieren, werden Sie den größten Teil Ihrer Arbeit wegwerfen, sobald der Code überarbeitet wurde.

Ich würde folgenden Ansatz wählen:

• Machen Sie die Dokumentation so unnötig wie möglich, indem Sie sich an die gängigen Best Practices halten. Wählen Sie gute Klassennamen, Methodennamen und Variablennamen, die Sie intuitiv verstehen können
• Zerlegen Sie riesige Monsterklassen und / oder Funktionen, wo es Sinn macht
• PHPdoc-Kommentare verwenden - Sie können Tools verwenden, um API-Dokumentation zu erstellen
• Schreiben Sie Tests dafür: Die Tests helfen Ihnen zu verstehen oder zu definieren, was der Code tun soll.

Jetzt haben Sie noch Dinge ohne Papiere: Dies können die allgemeinen Konzepte, die Architektur usw. sein. Dafür würde ich tatsächlich Dokumentation schreiben - aber nur das schreiben, was wirklich nützlich und hilfreich ist.