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.
