www.mikrocontroller.net

Forum: Mikrocontroller und Digitale Elektronik Dokumentationsmethode


Autor: Wolfgang Weinmann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,

mal eine Frage an Entwickler, die größere SW Projekte entwickeln. Mit
welcher Methode (Bsp. UML) dokumentiert oder modelliert Ihr Eure
Entwürfe?

Gruß

Wolfgang Weinmann

--
www.ibweinmann.de
Mikrocontrollersysteme

Autor: Rufus Τ. Firefly (rufus) (Moderator) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Handschriftliche Notizen mit einem stumpfen Bleistift, angefertigt auf
der Rückseite eines Kassenbons.

... jedenfalls gewinne ich bei manchen Software-"Projekten" diesen
Eindruck.

Autor: mkmk (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Meine Software (ob jetzt für eine Desktop Applikation, oder ein
Controller Project) ist strikt modular aufgebaut. Nie werden 2
verschiedene Aufgaben in einem Modul gelöst, und wenn sie noch so klein
sind.
Jedes Modul hat in der Kopfzeile eine Beschreibung der Funktion.
Innerhalb des Moduls haben alle Funktionen eine mehr oder weniger
ausführliche Beschreibung.
Und je nach Schwierigkeitsgrad haben Programzeilen einzeilige oder
mehrzeilige Beschreibungen.

Nie (!) betrüge ich mich der Ausrede "ach, die Funktion ist glaskar,
da braucht man keine Erklaerung zu schreiben". Jede glasklare Funktion
wird proportional zur verflossenen Zeit zu einer trüben Suppe.

Desweiteren hat jede Software eine Revision Nummer im Format x,xxx und
eine Revision Datei, wo jede noch so kleine Aenderung eingetragen wird,
nachdem die Revision Nummer inkrementiert wurde. Diese Revision Datei
ist in HTML Format und auch für die Kunden einsehbar.

Wenn ein Help-Sistem vorgeschrieben ist, wird's schwierig. Die beste
Erfahrung habe ich damit gemacht, dass ich, sobald ein Modul fertig
war, dafür die Help-Seite erstellt habe. Das bremst aber die
Kreativitaet ungemein. Aber zuerst die Software erstellen und dann die
Help Dateien ist purer Masochismus.

Autor: The Daz (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Oh je. Die ewige Frage nach Dokumentation. UML, java-doc, etc. sind gut
um Referenz-Dokumente zu erstellen. Aber um den Kern rueberzubringen,
geht es nicht ohne Prosa in Form von Textdokumenten. Man sollte4 halt
dafuer sorgen, dass die Doku ohne Probleme hinterher gelesen werden
kann (HTML/PDF). Das Problem ist aus meiner Sicht vor allem die
notwendige Sorgfalt, die Dokumentation auf dem neuesten Stand zu
halten.

Autor: Wolfgang Weinmann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,
ich habe mehr an das Modellieren des Softwaresystems gedacht. zunächst
gibt es ja die Anforderungen, was das System können muß. Und dann wird
ja bei größerer Software zuerst ein Modell gemacht. Diese Ebene meine
ich. Welche Modellierungsmethode setzt Ihr da ein.

Gruß

Wolfgang

Autor: Tomy (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert

Autor: Michael (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Ich habe mir mal Deinen Internetauftritt angesehen. Nachdem, was dort
aufgeführt ist, müßtest Du das ja schon alles selber wissen ?

Autor: Wolfgang Weinmann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
<<Ich habe mir mal Deinen Internetauftritt angesehen. Nachdem, was dort
aufgeführt ist, müßtest Du das ja schon alles selber wissen ?>>

Ich habe auch mit diversem Erfahrung (Strukturierter Analyse,
Strukturiertem Design, UML), was bei großen Projekten eingesetzt wurde.
Aber ich habe bisher keine Methode kennengelernt, die mir gut gefallen
hätte.

Gruß Wolfgang

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,

also ich denke mal es kommt auf den Kontext an in dem man eine Technik
oder Methode einsetzt. Für eine Anwendung die wenige byte groß ist wird
die UML kaum ein geeignetes mittel sein und für eine Lösung die mit
einer Objektorientierten Zielsprache realisiert wird ist die SA auch
nicht das geeignete Mittel. Im übrigen ist die UML keine Methode
sondern nur eine Notation. Was mich erstaunt ist auch das ein Mann mit
derartigen Projekterfahrungen diese Frage stellt. Sorry ich habe vor 20
Jahren auch in der militärischen Softwareentwicklung gearbeitet und dort
haben wir durchaus die damals Zeitgemäßen Methoden, Techniken und
Werkzeuge eingesetzt. Damals waren es halt Programmablaufpläne, Die SA
das ERD und Struktogrammtechnik. Kann sein das das bei uns in der DDR
damals anders gehandhabt wurde als bei solchen Projekten wie dem
Eurocopter grübel... Der aktuelle Stand der Darstellungstechnik ist
eindeutig die UML, vor allem auch weil dies ein internationaler
Standard ist.

Autor: Wolfgang Weinmann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
<<Was mich erstaunt ist auch das ein Mann mit
derartigen Projekterfahrungen diese Frage stellt.>>

Was mich etwas nervt ist, wenn man mir sagen will, was ich zu fragen
habe.

<<Der aktuelle Stand der Darstellungstechnik ist
eindeutig die UML, vor allem auch weil dies ein internationaler
Standard ist.>>

Und - mich interessiert trotzdem wer welche Dokumentationsart
einsetzt.

Wolfgang

Autor: Ingo (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Anforderungen: Planguage (Tom Gilb)
Erstentwurf: Texte, Szenarien, mit UML dargestellt.
Vorgehen bei Analyse, Design, Implementierung: Inkrementell, wenn die
Anforderungen klar sind. Bei Forschungsanteilen evolutionär. Wenn mir
einer Wasserfall aufdrücken will, versuche ich schnell weg zu laufen.

Dokumentation der Softwaremodule/klassen/Komponenten wo möglich mit
doxygen oder javadoc (je nach verwendeter Sprache).

Bei großen Projekten noch Design Dokumente und
Implementierungsdokumentation. Letzteres ist m.E. aber immmer kritisch,
da sowas später nur selten sauber gepflegt wird.

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hm,

sorry für die dumme Bemerkung... war eben nur verwundert... was habt
Ihr den beim Erocopterprojekt benutzt? also bei uns wurde damals sowas
wie das V-Modell benutzt... ich hoffe jetzt läuft Ingo nicht gleich
weg. ich bezweifle aber das inkrementelle Vorgehensweisen bei der
Projektkalkulation wirklich helfen, hier schwöre ich auf
Phasenkonzepte, Projektstruktrurplan und den guten alten Netzplan...
im richtigen Verhältnis zu iterativer Vorgehensweise... Dokus sind nach
wie vor als Textdokumente zu erstellen, dazu gibt es Gliederungen die
der jeweils eingesetzte Softwareprozess eigentlich vorschreibt...
gleichzeitig sind die Modelle der UML im entsprechenden Tool auch als
Doku zu werten die dann durchaus auch als HTML Doku oder mit einen
Reader für das Repository lesbar sind... das mehr oder weniger
militärischc V-Modell stellt da doch ganz klare Forderungen wie die
Dokus für jede Phase auszusehen haben...  wer das nicht mag greift nach
moderneren Konzepten wie den RUP, der ist iterativ und definiert auch
das Dokumentationsmodell, aber auch ein Blick in die klassichen
Gliederungen von Lastenheft und Pflichtenheft helfen da weiter,
desweiteren ist die Rechtslage auch ziemlich klar und definiert
Software erst dann als vollständig wenn eine Benutzerdokumentation und
eine Systemdokumentation vorliegen, Die Systemdoku übernimmt die UML,

noch ein Tipp, international und national geht der trend in der
Softwarbranche in richtung CMM oder in Europa SPICE in diesem Umfeld
sind auch eindeutige Forderungen an die Dokumentation gestellt

hm... eigentlich fragt sich was willst du überhaupt Dokumentieren?
- Analysedoku, Anforderungen?
- Entwurfsdoku ? projektbegleitenede Dokus?
- Dokus für Übergabe an Kunden?
- oder oder oder?

Autor: Wolfgang Weinmann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
<<was habt Ihr den beim Erocopterprojekt benutzt?>>

ich war bei der LFK - die hat das Panzerabwehrsystem geliefert.
Da das Projekt von der ersten Ansätzen bis zur Serienreife ca. 10 Jahre
gelaufen ist und somit der Start schon länger zurückliegt, ist das
Projekt mit Strukturierter Analyse/ Strukturiertem Design modelliert
und dokumentiert worden.

Die UML habe ich halt mal auf einem Lehrgang kennengelernt. Aber ich
habe einfach kein Aha-Erlebnis dabei gehabt.

<<also bei uns wurde damals sowas wie das V-Modell benutzt>>
Jetzt will ich mal genau sein. Das V-Modell ist ein Vorgehensmodell und
sagt nichts über die Modellierungsart aus. Und Ingo braucht auch nicht
wegzulaufen. Denn wenn man das V-Modell aufs wesentliche zusammenfaßt,
dann bleibt übrig, was jeder halbwegs gute Entwickler von sich aus
machen würde: Eine Entwicklung in Stufen zu machen von den
Anwenderforderungen, Grobentwurf, Feinentwurf, Implementierung und die
entsprechenden Test wie Modultests, Integrationstests und Systemtests.
Und das ist auch sinnvoll so. Es ist praktisch ein Vorgehen, um ein
riesiges Proojekt überhaupt halbwegs ordentlich durchzubringen.

Inkrementelle Vorgehensweise halte ich bei großen Projekten für
zwingend.
<<das mehr oder weniger
militärischc V-Modell stellt da doch ganz klare Forderungen wie die
Dokus für jede Phase auszusehen haben>>

Es steht drin was dokumentiert sein muß, nicht aber wie!

<<wer das nicht mag greift nach moderneren Konzepten wie den RUP>>

soweit ich weiß, wird Rational nicht dem Anspruch einer Methode
gerecht.


<<eigentlich fragt sich was willst du überhaupt Dokumentieren?>>

Meine jetzige Tätigkeit hat nichts mehr mit den riesigen Projekten von
früher zu tun.

Mich interessiert, wie man Systeme mit Interrupts und parallelen
Prozessen und das zeitliche Verhalten am besten modelliert.

Gruß

Wolfgang

Autor: Ingo (noch nicht weggelaufen) (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
@Alex: Die von Dir erwähnten Methoden sind natürlich bei großen
Projekten unerlässlich, haben aber zuerst mal keinen Entwicklungsbezug
sondern sind Teil guten Projektmanagements und damit für ein
Entwicklungs_projekt_ zwingende Voraussetzung. Ansonsten weiß man ja
nicht was, wann, zu welchen Kosten fertig wird.

Daher auch mein Hinweis auf die Anforderungsanalyse und Planguage. Ohne
klare Anforderungen helfen nämlich auch bestes Projektmanagement, die
tollsten Entwicklungsmethoden und die besten Entwickler nichts. Da
haben wir beide sicherlich schon unsere (leidvollen) Erfahrungen
gemacht.

@Wolfgang: Wenn es nur um das Modellieren von Systemen mit Interrupts
und parallelen Prozessen geht: Ich habe für sowas die UML, bzw. als es
die noch nicht gab, OMT, und davor Fluß- Nassi-Shneidermann sowie
Zustandsdiagramme verwendet. Die UML hat m.E. nur das Beste von vielen
anderen Methoden vereinheitlicht. Timingdiagramme, die für das
Modellieren von Parallelen Prozessen manchmal ganz hilfreich sind,
finde ich in der UML 2.0 aber nicht so gelungen. Da läßt man sich
besser von den Timingdiagrammen in einer Prozessorbeschreibung o.ä.
inspirieren.

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
hm... wollte ich auch gerade sagen... die UML bietet doch jetzt mit der
Version 2.0 ne menge für den Bereich ... zum einen ein ganz neues
Diagramm das Timing Diagram und das Aktivitätsdiagramm wurde
überarbeitet, kann sowohl nebenläufigkeiten als auch
Unterbrechungsregionen recht gut darstellen und ist jetzt auch in der
Lage wie ein Petrinetz Token zu tragen und Abläufe zu simulieren...
leider sind die Tools noch nicht soweit... zusätzliche kann die UML 2
auch angepasst werden (profil) so gibt es berteits ein spezielles
UML-Profil für den geforderten Bereich die UML-RT ...

tja RUP ist auch keine Methode sondern ein Vorgehensmodell und genau
wie das V-Modell fordert es was zu Dokumentieren ist... die
Gliederungen werden hier auch nur vorgeschlagen sind aber nicht
verbindlich, Die einzigsten halbwegs verbindlichen Gliederungen die mir
jetzt einfallen sind tatsächliche Lastenheft und Pflichtenheft die sind
durch VDE/VDI genormt (VDI/VDE 3694, Lastenheft/Pflichtenheft für den
Einsatz von Automatisierungssystemen)

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
ach so noch was... das Timingdiagramm der UML soll genau so wie die
guten alten Diagramme die wir aus den Prozessortiming kennen gezeichnet
werden... leider sind die Lehrbuchbeispiele nur immer so doof weil die
Autoren in den seltenstemn Fällen aus dem Hardwarenahen bereich kommen

Autor: Ingo (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Für dynamische Modellierung verwende ich sowohl Aktivitäts- als auch
Zustandsdiagramme, ja nachdem was gerade besser passt.

Auf der Toolseite habe ich schon mit einigen z.T. sehr leidvolle
Erfahrungen machen müssen. Meine Favoriten:
- Visio mit den UML Plugins von Fleury (IIRC), wenn's nur ums einfache
Zeichnen geht. Das Plugin unterstützt die UML 2.0 vollständig und ist
sehr einfach zu verwedenen.
- Together, wenn man in größeren Teams arbeitet und Java oder C++ Code
reengineeren will. Nachteil: Sehr teuer (IIRC > 2000€).
- Enterprise Architect. Preiswert, UML2.0 konform, integrierte
Versionsverwaltung. Kann Code generieren und Dokumentation erzeugen.
Kostet im Moment so ca. 200€ und ist damit mein Favorit.


Ein Tool möchte ich natürlich nicht unerwähnt lassen:

Whiteboard und s, r, g, b-Stifte. Da passen alle Ideen drauf. Es
Unterstützt alle Modellierungsmethoden und funktioniert mit jedem
Vorgehensmodell.
Von allen erwähnten Werkzeugen haben mir das Whiteboard, die Stifte und
die Diskussion mit meinen Kollegen am meisten geholfen, brauchbare
Designs zur schaffen und Fehler zu vermeiden.

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
ja na klar Tafelarbeit ist extrem wichtig... hier noch mein letzter Tipp
für heute... CRC Karten im A4 Format, Magnete und Stifte sind eines der
besten mittel im Team sinnvolle Klassenmodelle zu erstellen, mit ner
guten DigiCam kann man die Tafelbilder auch schön festhalten... der EA
ist OK hat aber schon noch einige Macken und die wechseln mir die
Versionen zu oft, wir haben einiges in Rational gemacht aber da ist der
Preis abartig

Autor: Wolfgang Weinmann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
@Ingo:
<<Timingdiagramme, die für das
Modellieren von Parallelen Prozessen manchmal ganz hilfreich sind,
finde ich in der UML 2.0 aber nicht so gelungen. Da läßt man sich
besser von den Timingdiagrammen in einer Prozessorbeschreibung o.ä.
inspirieren.>>
Das drückt meinige Enttäuschung vom UML-Lehrgang auch aus. Nach
jahrelangem Strukturiertem Vorgehen hatte ich einen großen Fortschritt
erwartet und am Ende hatte ich halt etwas ein Gefühl der Ernüchterung,
daß um die UML so ein Wirbel gemacht wurde. War nichts Sensationelles.

Aber inzwischen bin ich mit der Diskussion zufrieden - ich werde mal
ein paar Diunge, die gefallen sind anschauen und vielleicht auch
nochmal einen Blick auf die UML werfen. Als ich noch bei der EADS war,
waren diese Themen halt Tagesgeschäft. Aber seit zwei Jahren
beschäftige ich mich mit Controllersystemen und da wollte ich einfach
mal so sehen, was sich inzwischen getan hat.

Gruß

Wolfgang

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
in einem hast du recht... die UML bietet auf den ersten Blick wenig an
den Konzepten die zum Beispiel in der SA durch schrittweise
Verfeinerung zu übersichtlichen Modellstrukturen geführt hat... auch
hier hat die UML  2 nachgelegt, das Paketkonzept und die
Diagrammzusammenhänge wurde semantisch stark aufgewertet und man kann
durchaus tugenden der Strukturierung wie schrittweise Verfeinerung und
übersichtliche Darstellungen auch mit der UML erreichen und soll dies
auch ausdrücklich tun, im übrigen sind meine Erfahrung die das
tatsächlich in UML Kursen die UML nur sehr oberflächlich behandelt
wird. die Basiskonzepte der Objektorientierung werden meist zugunsten
der überfrachteter Notationsschulung... ich habe zur zeit einen Kunden
der möchte UML 2 aber keine Basiskonzepte der Objektorientierung und
Grundlagen und erst rechts nichts zum Metamodell der UML hören und
genau das funktioniert nicht wirklich... mein Tipp: neben der
Sekundärliteratur aus dem Buchhandel auf jeden Fall die
Orriginaldokumente der UML studieren. die sind frei im netz verfügbar
und die einzig wahre Quelle ;-) leider sehr formal und nicht gerade mit
spaß zu lesen :-/ www.uml.org

Autor: Gerd Laschinski (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,

eine sehr interessante Diskussion, zumindest jetzt nach den ersten
Startschwierigkeiten. Danke an Wolfgang, daß er in meinen Augen weise
reagiert hat.
Kann jemand ein gutes Buch zum Einstieg in UML nennen. Mir ist schon
klar, daß man sich irgendwann mit der "einzig wahren Quelle" (Alex)
beschäftigen muß, aber so zum schnellen Einstieg gibt es möglicherweise
gute Literatur.

Gruß
Gerd

Autor: Alex (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Bernd Östereich, Obejektorientierte Softwareentwicklung mit der UML und
wer tiefer rein leuchten will die OMG Zertifizierungsbücher von der
selben Reihe ...

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]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [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.