Forum: PC Hard- und Software Wie sieht eine technische SW Dokumentation aus?


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
von Manuel (Gast)


Bewertung
0 lesenswert
nicht lesenswert
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

von Gero (Gast)


Bewertung
1 lesenswert
nicht lesenswert
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

von S. R. (svenska)


Bewertung
1 lesenswert
nicht lesenswert
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.

von Manuel (Gast)


Bewertung
0 lesenswert
nicht lesenswert
@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

von Axel S. (a-za-z0-9)


Bewertung
-2 lesenswert
nicht lesenswert
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 ...

von S. R. (svenska)


Bewertung
0 lesenswert
nicht lesenswert
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.

von A. S. (achs)


Bewertung
1 lesenswert
nicht lesenswert
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.

: Bearbeitet durch User
von Manuel (Gast)


Bewertung
0 lesenswert
nicht lesenswert
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

von A. S. (achs)


Bewertung
0 lesenswert
nicht lesenswert
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.

von Walter T. (nicolas)


Bewertung
1 lesenswert
nicht lesenswert
Und bei der Doku nicht vergessen, das "Lastenheft" nachzuliefern, 
ansonsten ist es schwer, später nachzuvollziehen, auf welchen Grundlagen 
die Designentscheidungen beruhen.

von A. S. (achs)


Bewertung
0 lesenswert
nicht lesenswert
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.

von doppelschwarz (Gast)


Bewertung
0 lesenswert
nicht lesenswert
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.

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.
Hinweis: der ursprüngliche Beitrag ist mehr als 6 Monate alt.
Bitte hier nur auf die ursprüngliche Frage antworten,
für neue Fragen einen neuen Beitrag erstellen.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.