Hallo zusammen, Ich möchte einen abgeschlossen Projekt "SW Entwicklung" technisch dokumentieren. Das grobe Ablauf ist schon festgelegt und auch dokumentiert. Da es diese SW vierl erweitert wurde und dazu sind mehrere Module dazu gekommen, die es leider nirgendwo dokumentiert. Es ist die Zeitpunkt gekommen alles zu dokumentieren mindesten die technische Seite. Meine Frage an euch: Wie soll ich das technisch dokumentieren ? Reicht es eine UML Model zu zeichen? Soll ich alles betrachten sogar if und While .....? Wie soll eine technische Dokumentation aussehen? Danke und sorry für die blöde Frage
ich würde eher sagen dass eine techn. Dokumentation die übergeordnete Funktion beschreibt - was macht die Software sowie die Beschreibung input <-> output. (Was tippt der user ein, welche Funktionen bietet die Software, für was benütze ich das Ding...) Eine UML gibt dann Aufschluss über das Zusammenspiel deiner Funktionen und Methoden. Diese Funktionen dokumentiere ich dann eigentlich ausschließlich im Quelltext! eine Beschreibung jeder if und while gehört imho nicht in eine Dokumentation, dafür gibt es den sourcecode wo Du überigens über jede Funktion nochmals input und output aufzählen solltest. jm2c
Wenn festgelegt ist, wie und was dokumentiert werden muss, dann solltest du dich danach richten. Ansonsten solltest du mindestens Schnittstellen und Verhalten beschreiben. Die Schnittstellen müssen dokumentiert sein, damit das Programm später anhand der Dokumentation erweitert (oder in Teilen ersetzt) werden kann. Das heißt konkret, welche Daten gehen in ein Modul rein, welche Daten kommen aus einem Modul raus, wie kann ich das Modul anweisen, seine Funktion durchzuführen. Die Dokumentation beschreibt also APIs, Protokolle, was für das Projekt relevant ist. Jedes Modul wiederum hat ein Verhalten, und dieses muss beschrieben sein, damit man ein Modul testen oder ersetzen kann. Das heißt, auf welche Art werden die eingehenden Daten in die ausgehenden Daten transformiert und welche Seiteneffekte treten dabei auf. Möglicherweise kommt dazu noch eine getrennte Beschreibung der Oberfläche. Du beschreibst also: - die Struktur des Programms (Schnittstellenbeschreibung) - das Verhalten des Programms (Modulbeschreibungen) - die Benutzung des Programms (Oberflächenbeschreibung) Für alles gibt es passende UML-Diagramme, wobei ich Text mit erklärenden Bildern bevorzuge, also nicht strikt nach UML vorgehe.
@S. R. Danke für die Antwort. Ich habe es dazu noch eine Frage: Was soll ich in : S. R. schrieb: > - das Verhalten des Programms (Modulbeschreibungen) beschreiben? Eine beispiel wäre gar nicht schlecht Danke
Manuel schrieb: [Kauderwelch gesnipt] > Wie soll eine technische Dokumentation aussehen? Eine Dokumentation sollte vor allem (auch) grammatikalisch und orthographisch korrekt sein. Fang damit an. Wenn du das kannst, klären wir die Feinheiten ...
Manuel schrieb: > Was soll ich in : >> - das Verhalten des Programms (Modulbeschreibungen) > beschreiben? Welche Daten gehen in das Modul rein (und was bedeuten sie), welche Daten kommen aus dem Modul raus (und was bedeuten sie), welche Beziehung besteht zwischen Eingabe- und Ausgabedaten, welche Seiteneffekte treten auf. Manuel schrieb: > Eine beispiel wäre gar nicht schlecht Ich mache deine Hausaufgaben nicht. Es gibt genug technische Dokumentation da draußen. Finde etwas, was dir vom Layout zusagt, und orientiere dich dran. Stelle sicher, dass es lesbar, verständlich und vollständig(!) ist.
Die erste Frage ist: für wen? Zulasser? Kunden? Programmierer, als Nutzer der SW (z.b. als Library)? Spätere Programmierer des Codes? Tester? Marketing? Maschienendoku? Eine allgemeine Übersetzung von Quelltext in "verständliche Sprache" ist Unsinn. Dann lieber Refactoring. Bei einem Schaltplan käme auch niemand auf die Idee, textuell zu beschreiben, dass pin3-uC auf pin7-ic2 geht. Zuviel ist genauso schlimm wie zu wenig. Maßgeblich ist eh nur der Quelltext. Aber eigentlich hast du doch schon eine Vorlage, die alten Module sind doch dokumentiert.
Achim S. schrieb: > Aber eigentlich hast du doch schon eine Vorlage, die alten Module sind > doch dokumentiert Ne nicht wirklich dokumentiert. Es handelt sich nur um eine Skizze mehr nicht. Die zusammenhang zwischen die Module ist nirgendwo beschrieben. Die Interfaces ist auch nirgendwo dokumentiert. Damal vor 4 jahre als ich hier angefangen habe, war die Erbe ziemlich schlimm. Man hat nur Quellencode Quellencode... Mittlerweile ist das schon teilweise dokumentiert. Mir geht es darum: Die teschnische Dokumentation muss eigentlich für die SW entwickler geschrieben werden und nicht für z.B Vertriebsleute. Bis jetzt bin ich so vorgegangen: Das Konzept der SW in eine UML Form zusammengefasst. Erstmal in eine allgemeine Form dann step für step in Detail beschrieben aber immer in eine UML Form. Die Interfaces, die Module oder woraus zu achten ist (das Integrieren das System in einem anderen System z.B "von embedded zu C++ zu Labview"). Das habe ich in Text Form zusammengefasst. Ich weiss es nicht, ob es so Okay ist. Problem ist: Diese projekt ist echt so komplex geworden, dass es mehreren Interfaces beinhaltet( von HW zu SW und wie die zu einander stehen), die nicht mehr zu verstehen sind. --> Also einzige Lösung: Dokumentieren
Manuel schrieb: > --> Also einzige Lösung: Dokumentieren Richtig. Und bei dieser Zielgruppe Manuel schrieb: > Die teschnische Dokumentation muss eigentlich für die > SW entwickler geschrieben werden und nicht für z.B Vertriebsleute. machst Du das genau für eine Person: --> Für Dich!! Du wirst den Code beim Dokumentieren intensiv kennenlernen und das ist auch gut so. Allerdings, ... wenn der Code gut ist, wird Deine Dokumente keiner lesen. Einfach weil ein IDE-Browser viel, viel(!) besser über die relevanten Dinge navigiert als Word. Oder ein Browser für UML, dessen Semantik die meisten gar nicht so genau kennen. Es gibt ja meist auch kein Compiler/Lint-Äquivalent dass grobe Fehler aufdeckt. UML-Beschreibungen sind in den meisten Fällen Skizzen, in die man vage "offensichtliche" Bedeutungen legt (so a la "ich denke, es ist klar, was damit gemeint ist, das .... bedeutet hier ... "). Wenn der Code schlecht ist, dann wird man sich auf Deine Dokumente stürzen. Und dann feststellen, dass der Code leider dann doch nicht ganz so funtkioniert wie erwartet --> also wieder IDE-browsen. Eigentlich bleibt da nur Refaktoring. Eine wirklich grobe Beschreibung der Schnittstellen und Übergeordneter Konzepte sind manchmal noch wirklich hilfreich. So Dinge wie: die Init-Funtkionen müssen immer vor den Main-Funktionen aufgerufen werden, sonst knallts oder eben genau nicht. Oder ob Inits erneut erneut aufgerufen werden dürfen. Was machen alle Funktionen mit 0-Zeigern, Standard-Returnvalues und -Errorhandling. Für diese allgemeinen Dinge muss a) den Code gut kennen (so wie Du) und daraus b) einen gemeinsamen "Geist" herauskristalisieren, den man dann als Default-Verhalten definieren kann und alle Abweichungen davon langfristig rausfaktorieren. Auch z.B. Naming-Konventions lassen sich besser im Nachhinein "herauslesen", da a-priori-Konventionen meist (wie Sunzi schon vor zweinhalb-tausend Jahren postulierte) den ersten Codiertag nicht überleben.
Und bei der Doku nicht vergessen, das "Lastenheft" nachzuliefern, ansonsten ist es schwer, später nachzuvollziehen, auf welchen Grundlagen die Designentscheidungen beruhen.
Walter T. schrieb: > Und bei der Doku nicht vergessen, das "Lastenheft" nachzuliefern Das ist ein wirklich guter Einwurf. Das Lastenheft ("Was" und "Warum") ist zusammen mit dem Pflichtenheft ("Wie" und "Womit") das m.E. wirklich brauchbare Konzept. Solange sie nicht Implementierungsdetails festlegen oder gar Doku sein wollen. Sondern den Kern der Aufgabe und den Geist der Lösung vermitteln.
doxygen hilft sehr, den Aufbau des Programms zu verstehen. Da sieht man auch sehr schön, welches Modul mit welchem "arbeitet" und kann sich durchklicken. Jede Funktion hat eine Beschreibung mit Ein-/Ausgangsparametern und return-Werten. Das Ergebnis sollte zumindest schon mal deutlich weiter helfen, der Aufwand dafür hält sich in Grenzen, zumal man das eh machen sollte.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.