Ich bin damit beauftragt, den Dokumentationsaufwand für ein vorhandenes, vollständig undokumentiertes Softwareprodukt zu leiten. Welche Ressourcen helfen mir dabei?

Ich bin Softwareentwickler bei einem Technologieunternehmen. Ich wurde beauftragt, den Dokumentationsaufwand für das Produkt zu leiten, an dem ich arbeite. Ziel ist es, eine entwicklerinterne Dokumentation zu erstellen, und das Projekt wird auf die Geschäftsseite übertragen, wo es die Anforderungsdokumentation abdeckt.

Dieses Projekt ist eine Herausforderung. Insbesondere habe ich es mit einem Produkt zu tun, das: - schon lange existiert, mindestens 6 Jahre. - hat keine andere Form der Dokumentation als einige kleine, veraltete Stücke hier und da. - enthält Kommentare im Code, diese sind jedoch technisch und vermitteln kein übergreifendes Verhalten (auch nicht auf technischer Seite). - als Folge von wenig bis gar keiner Dokumentation, ist oft unnötig komplex unter der Decke

Außerdem haben wir nicht viel Zeit, um an diesem Projekt zu arbeiten.

Ich habe keine formellen Unterlagen oder schriftlichen Hintergründe, Schulungen oder Erfahrungen. Ich habe einige Fähigkeiten im Schreiben / Kommunizieren im Büro gezeigt, weshalb ich möglicherweise diesem Projekt zugewiesen wurde.

Bitte teilen Sie Ihren Rat oder Ihre Empfehlung für Ressourcen mit, die mir bei der Vorbereitung und Bearbeitung dieses Projekts helfen. Ich suche nach Verweisen auf Bücher / Websites / Foren / was auch immer, um einen Plan mit Meilensteinen zu erstellen, Best Practices, Aufgabendelegation, Vorlagen, Buy-In usw. kennenzulernen.

Ich hoffe speziell auf Ressourcen, die auf die Einführung einer guten Dokumentation in bestehende, nicht dokumentierte Projekte abzielen oder diese besonders erwähnen .

Normalerweise benutze ich ein Wiki und spamme dort oben nur Spam, während ich den Entdeckungsprozess durchlaufe. Wiki, weil Sie Such- und Verlaufsfunktionen sowie Teambearbeitungsfunktionen erhalten. Das genaue Tool ist weniger wichtig als eine funktionierende Suche und die Verwendung durch alle. Erwarten Sie, dass es anfangs sehr rau ist, aber ermutigen Sie die Leute, diese groben Notizen zu machen, während sie gehen, denn das ist alles, was Sie zuerst bekommen werden.

Ein paar Dinge, die sehr helfen:

• habe einen Editor. Sie wahrscheinlich zuerst, aber wenn Sie das Budget haben, machen Sie es Teil von jemandes Arbeit. Suchen Sie sich jemanden aus, der gut mit Sprache und nicht mit technischen Fähigkeiten umgehen kann. Bearbeiten Sie aus Gründen der Klarheit und nicht der Perfektion. Sie möchten die Benutzer dazu ermutigen, gute Einträge zu schreiben, müssen sie jedoch zunächst anleiten.
• Verwenden Sie Diagramme, setzen Sie jedoch voraus, dass ein relevantes Tool verwendet wird. Das Bild wird generiert und die Quelldatei an die Seite angehängt. Auf diese Weise können Benutzer Ihr Bild mit dem richtigen Werkzeug anstelle von MS-Paint bearbeiten. Wenige Dinge saugen mehr als ein wirklich gutes Diagramm in Visio, für das Sie das Quelldokument nicht mehr haben, sondern nur ein daraus extrahiertes PNG.
• Ermutigen Sie zur Neuanordnung und Bearbeitung. Auch wenn es zunächst nicht großartig ist, brauchen Sie Leute, die Informationen sammeln und Fehler korrigieren. Mentor Menschen, um dies gut zu machen.
• Bringen Sie dies bei Ihren wöchentlichen Teambesprechungen zur Sprache. Holen Sie sich die Liste der letzten Änderungen, bevor Sie hineingehen, und loben Sie Leute, die etwas Nützliches hinzugefügt haben, und fragen Sie dann, warum diejenigen, die dies nicht getan haben, es nicht getan haben.

Ich habe in der Vergangenheit mit einem Image einer virtuellen MediaWiki-Maschine begonnen, weil es sehr schnell und einfach zu starten ist, sodass Leute, die sagen "es ist zu schwer", keine anfängliche Traktion bekommen.

Wenn Ihre Sprache / Umgebung dies mit JavaDoc / NDoc-Tools unterstützt, um die Kommentare beim Hinzufügen zu extrahieren, ist dies ein guter Ansatz auf niedriger Ebene. Dies ist jedoch weniger nützlich als die Dokumentation auf hoher Ebene, und obwohl die Tools das Hinzufügen von Inhalten auf höherer Ebene unterstützen, ist es unnötig mühsam, sie nur mit diesen Tools aus dem Nichts zu erstellen.

Wenn Sie den Code selbst dokumentieren und keine Endbenutzerdokumentation durchführen, ist Doxygen ein hervorragendes Tool, wenn Ihre Entwicklungssprachen unterstützt werden. Sie führen es über Ihren Code aus und es wird eine Website erstellt, auf der alle Ihre Funktionen, Klassen usw. aufgelistet sind. Anschließend können Sie speziell formatierte Codekommentare hinzufügen, um Dinge zu gruppieren und weitere Details hinzuzufügen. Es ist eine großartige Möglichkeit, eine Codebasis schrittweise zu dokumentieren.

In Bezug auf die Dokumentation des Codes selbst stehen viele alternative Tools zur Verfügung, wenn Doxygen nicht Ihren Anforderungen entspricht. Wikipedia hat eine Liste von fast 50 solcher Tools und enthält Details zu deren Funktionalität und Sprachunterstützung.

Haftungsausschluss: Ich bin mit einem der Tools verbunden, Imagix 4D .

Dies sind nur einige Ideen, die auf einer bestimmten Ebene nützlich sein können:

Haben Sie darüber nachgedacht, wie diese Dokumentation am Ende aussehen wird: Es handelt sich um ein Word-Dokument, eine DVD, eine Site mit einer Reihe von Seiten, auf denen die Anwendung aufgeschlüsselt ist, ein Blogging-Tool, das beim Durchtauchen nur Details der Anwendung abrüttelt Verwenden Sie ein Standard-Dokumentenverwaltungssystem wie Share Point oder etwas anderes? Das Erhalten von Ergebnissen wäre ein Beispiel für ein Online-Buch, das beispielsweise aus einer Reihe von Seiten besteht.

Welche Art von Versionskontrolle und Bearbeitungsprozess diese Dokumentation ausführen soll, ist ein weiteres Problem, über das Sie möglicherweise nachdenken sollten, bevor Sie zu weit gehen. Wie möchten Sie mit Aktualisierungen und Änderungen umgehen?

Feedback ist wahrscheinlich eine weitere interessante Dimension, da alles, was Sie dort erstellen, wahrscheinlich mehr als nur ein paar Kritikpunkte enthält. Wie gut diese Änderungen priorisiert und gedrosselt werden, ist eine weitere Frage, die ich in Betracht ziehen würde, bevor ich diese erste Version herausbringe.

Viel Glück!

Das Erstellen von Dokumentationen ist wie das Erstellen aller anderen Arten von Software ein von Natur aus komplexer Prozess.

Deshalb haben Softwareentwickler die Agile-Methoden erfunden.

Dokumentation ist nur Software ohne Compiler. Die gleichen Methoden für Softwareprojekte gelten für Dokumentationsprojekte. Genau die gleiche Argumentation.

Wenn Sie Software schreiben, beginnen Sie mit Anwendungsfällen (oder User Stories). Die Dokumentation ist nicht anders.

Sie priorisieren die Anwendungsfälle mit einem ungefähren Budget.

Du hast Sprints.

Sie haben Veröffentlichungen.

Sie führen Qualitätssicherung durch - Testen - Überprüfen - Korrigieren und erneutes Freigeben.

Es ist genau wie beim Erstellen von Software.

Wer sind deine Benutzer? Welche Probleme haben sie? Wie wird das Dokument ihr Problem lösen? Priorisieren. Sprint. Schließlich werden Sie freigeben.