Hat von Euch jemand ne Idee, wie man ein Software-Projekt in einer
Dokumentation am besten zusammenfassen kann? Wenn ich nen "normales"
Thema hätte wie etwas mit Versuchen, dann hätt ich die Kapitel z.B.
Einleitung
Stand der Technik
Versuchsbeschreibung/Durchführung
Diskussion der Ergebnisse
Zusammenfassung und Ausblick
Aber bei einer Software z.B. für einen Mikrocontroller? Einleitung klar
- aber dann? Wenn jemand nen Tipp von Euch hat, wuerd ich mich freuen.
Software-Projekt dokumentieren schrieb:> Einleitung
Ist klar.
> Stand der Technik
was gabs bisher in der Richtung? Vorarbeiten?
> Versuchsbeschreibung/Durchführung
Hier würde ich eher in die Richtung Planung/ Übersicht gehen.
Je nach Progrämmchen UML, Ablaufdiagramme, Algorythmen (falls das nicht
schon in den Grundlagen geklärt wurde)
> Diskussion der Ergebnisse
Hier dann Test der Software mit den Testergebnissen, wo die Software
bereits taugt, wo noch Fehler auftreten usw.
> Zusammenfassung und Ausblick
Ist klar.
Das wäre mal so ne grobe Näherung, eine allgemein gültige Richtline
gibts für sowas nicht, hängt viel zu sehr vom Projekt selbst ab.
Dein Vorschlag sieht so aus, als ginge es um eine Abschlussarbeit oder
"Hausaufgaben". Falls es sich stattdessen "nur" um eine "richtige"
Softwaredokumentation handelt, würde ich wie folgt vorgehen:
- Quellcodedokumentation z. B. mit Doxygen o. ä.
- Dazu gehört implizit auch eine korrekte "Versionsverwaltung", d. h.
zumindest das Aktualsieren (bzw. automatisch generieren lassen) von
Änderungsaten und Change History in den Dateien
- Dazu kann man noch etwas Prosa verfassen, z. B. ein Word-Dokument
(bitte nicht schlagen dafür), das die Funktionalität grundsätzlich bzw.
Dinge wie Pin-Zuordnungen, externe µC-Beschaltung, Fuse Settings beim
Programmieren etc. zusammenfasst. Hier gilt es, einen Mittelweg zu
finden, um möglichst Redundanzen zu vermeiden (das Meiste steht ja schon
im Quelltext bzw. im Schaltplan); evtl. reicht ja eine
"Bedienungsanleitung" der Software.
Patrick schrieb:> als ginge es um eine Abschlussarbeit
ja, es geht um eine Abschlussarbeit.
Floh schrieb:> Hier würde ich eher in die Richtung Planung/ Übersicht gehen.> Je nach Progrämmchen UML, Ablaufdiagramme, Algorythmen (falls das nicht> schon in den Grundlagen geklärt wurde)Floh schrieb:> Hier dann Test der Software mit den Testergebnissen, wo die Software> bereits taugt, wo noch Fehler auftreten usw.
Vielen Dank für diese beiden Ideen, ich glaube, dies sind gute Ansätze,
wie ich den Kram schriftlich umsetzen kann.
Gut.
Ergänzend vielleicht meine Kommentare, wie ich SW-Dokumentation
aufteile. Ich arbeite im Bereich Automotive, und mache viel
Schnittstellenentwicklung und Prototypenarbeit, dh, meine Dokumentation
wird übergeben und Leute arbeiten damit. Im Laufe der Zeit kommen immer
wieder dieselben Sachen zusammen.
1) Für Anwender:
Kurzes Tutorial, zB wie installiere und konfiguriere ich das Ding.
2) Für Entwickler
- Projektübersicht mit kurzem Prosatext, evtl 1,2 Konzeptdiagrammen aus
Usersicht, Links zu wichtigen Dokumenten, Datenblättern, usw. im
jeweiligen SVN (das zT einfach zu groß ist, um schnell was zu finden).
- Hardwareübersicht mit den relevanten Infos für Entwickler, hier im
µControllerbereich die Pinbelegungen, oft Skizzen von Prinzipschaltungen
(bzw. einfach Fotos davon)
- Anleitung zum Aufsetzen der Entwicklungsumgebung,
Compilereinstellungen, Links zu Software usw. - wie bringe ich das Ding
erstmalig auf meinem Rechner zum Laufen?
- Softwareübersicht, ein bisschen UML
- Dokumentation aller Schnittstellen inkl. Besonderheiten und Protokoll,
soweit vorhanden, Minimalbeispiele
- Dokumentation aller Algorithemn
- ROADMAPS AND ROADBLOCKS als wichtigster Teil der Doku (das hab ich vor
einigen Jahren mal gehört und es is tmir immer im Kopf geblieben.)
* Roadmaps sind Anleitungen, die vorhergesehene Fälle für Entwickler /
insb. Instandhalter geben, aka: "Wie lese ich eine weitere zyklische
CAN-Variable ein?"
* Roadblocks sind eben Blockierer, die auftreten können - "Was mache
ich, wenn der Parser meine Config-Datei nicht nimmt? Was mache ich, wenn
die Kamera die IP-Adresse verliert? Was mcahe ich, wenn der OEM wieder
mal das Steuergerät updatet?"
+ gute Kommentare und Beschreibungen im Code und ausführliche Beispiele
bei APIs.
...
Natürlich ist so was der Idealfall, aber 50% dieser Daten
(Schnittstellenbeschreibungen, Hardwareinfo) entstehen ohnehin beim
Entwickeln, 20% als Vorbereitung für irgendwelche Meetings und der
Rest.. nun ja, ich nehme mir einfach konsequent jeden Tag 10-20 Minuten
dafür.
Hallo,
einen Tipp zu Doxygen. Ich stelle fest, dass viele Entwickler das als
Allheilmittel benutzen. Also nur Funktionen Dokumentieren aber deren
Zusammenhang untereinander überhaupt nicht darstellen. Spätestens bei
großen Projekten ist das schnell zum Scheitern verturteils.
Eine ordentlich ausformulierte Softwarespezifikation und mit UML als
Ergänzung trägt um einiges mehr zum Verständnis bei.
Beschreibung von grob nach fein und eventuell auch objektbezogen
dokumentieren (auch wenn nicht objektorientiert wurde). Z.B. die
Software in Blöcke aufteilen (ähnlich wie die Blöcke bei den einzelnen
uC Teilen): ein Block kümmert sich um Analogverarbeitung, der nächste
Block macht die Verarbeitung des HID, der nächste Teil die Motorregelung
(usw.).
Auch immer gut kommt: Use Cases, Requirements.
Was noch nicht erwähnt wurde: Begründungen für Designentscheidungen,
gerade wenn man (mit gutem Grund) irgendetwas nicht so macht wie man
erwarten würde/einen typischeren Ansatz verworfen hat.
Den Ablauf usw. zu beschreiben ist schön. Nützlich wäre jedoch, einige
Hinweise zur Fehlersuche hinzuzufügen, da in x Jahren garantiert keiner
mehr da ist, den man fragen kann.
oszi40 schrieb:> Nützlich wäre jedoch, einige> Hinweise zur Fehlersuche hinzuzufügen, da in x Jahren garantiert keiner> mehr da ist, den man fragen kann.
An was denkst du dabei? (Ernsthaftes interesse, mir fällt da gerade nix
zu ein?)
>Den Ablauf usw. zu beschreiben ist schön. Nützlich wäre jedoch, einige>Hinweise zur Fehlersuche hinzuzufügen, da in x Jahren garantiert keiner>mehr da ist, den man fragen kann.
???
Nützlich ist, die Funktion des Codes zu beschreiben, nicht die Hinweise
zu einer Fehlersuche. Ob und wie ein Fehler auftaucht, weiß ich
persönlich nicht von Vornherein!
Rosa
Hmm.. wie erwähnt, Troubleshooting-Hinweise machen absolut Sinn.
Nicht bei so kleinen Bastelprojekten, wo man als Einzelperson relativ
schnell alles durchschaut, aber..
Ich arbeite zum Beispiel an C++-Software, die in mehreren Prüfständen
eingesetzt wird (und da auch auf Hardware zugreift, und angepasst und
konfiguriert werden muss), und mit Schnittstellen zu LabVIEW, S7,
Beckhoff, CAPL und C# (mit jeweils eigenen Softwareprojekten dahinter),
kommuniziert.
Damit bin ich zentraler Ansprechpartner für so gut wie alle
Schnittstellen in unserem Laden.
Nicht jeder meiner Kollegen
a) kann alle Sprachen und kennt die Softwarekonzepte
b) kennt die Hardware und ihre Tücken
c) kennt den spezifischen Prüfstand
d) hat im Fehlerfall Zeit sich durch viele Mannjahre an Framework und
Konzepten durchzukämpfen, nur weil zB eine Schnittstelle um einen Wert
erweitert werden muss, oder mit einem Gerät partout keine Kommunikation
zustande kommen kann (wofür es eine endliche Anzahl an Möglichkeiten
gibt, die man aber wissen muss), oder die blöde Canalyzer-Library "42"
als Wert zurückgibt.
Und woher soll ein Nicht-SPS-Programmierer auch wissen, dass TwinCAT
nach Neuinstallation bei bestimmten AMD-Dualcores zu Bluescreens führt,
es sei denn, man ändert einen Registry-Wert?
Natürlich kann man nicht vorhersehen, was an Problemen auftritt, sonst
würde man ja auch möglichst viel abfangen und gute Softwarelogs
schreiben. Aber mit der Zeit kennt man die kritischen Stellen, und wenn
man, statt einer Antwort per Email eine Antwort ins Wiki schreibt,
hilfts beim nächsten Mal. (und das tuts wirklich. Ich hab für ein
bestimmtes, besonders fieses Gerät inzwischen eine
3-seitige-Troubleshooting-Checkliste, und das löst 98% aller Probleme
damit.)
Deswegen: Ja, es kann absolut sinnvoll sein, Fehlersuchanleitungen zu
schreiben. Vor allem, wenn man das "große Bild" sieht, und unter Fehlern
nicht die kleinstmöglichen Einheiten ("echte" Programmier/Logikfehler,
die eigentlich durch Unit-Tests ausgemerzt sein sollen, in der Realität
aber vielleciht doch drin bleiben) versteht. Und selbst da kann man mit
einem guten Tracing-Konzept, und einer Anleitung, wie es angewandt wird,
seinen Kollegen helfen.
---
Und ja: Ungewöhnliche Design-Entscheidungen gehören absolut
dokumentiert. Mit Begründung.
Genauso wie schwer lesbare Optimierung.
> ob Fehler auftaucht, weiß ich persönlich nicht von Vornherein!
Das wissen wir auch nicht, aber offensichtliche Sachen, wie "fehlende
externe Impule erzeugen folgende Meldung xyz" od. "wenn grüne LED blinkt
fehlt Wasser" ... würden den späteren Support wesentlich erleichtern.
oszi40 schrieb:> Das wissen wir auch nicht, aber offensichtliche Sachen, wie "fehlende> externe Impule erzeugen folgende Meldung xyz" od. "wenn grüne LED blinkt> fehlt Wasser" ... würden den späteren Support wesentlich erleichtern.
Gebrauchsanleitung nennt man das für gewöhnlich.
So im Groben:
Gabs kein Lastenheft?
Daraus folgt gewöhnlich ein Pflichtenheft mit
den Spezifikationen, Strukturen und Designflow.
Algorithmen wurden ja schon genannt.
Gut kommentiertes Listing.
Schaltpläne, Layout und Bauteillisten mit Beschaffungsquellen
nebs secondary source.
Funktionsbeschreibung und Prüfanweisungen/-protokolle z.B. EMV
Kostenkalkulation
Gebrauchsanleitung mit Stichwortverzeichnis
Jeden Punkt kann man dann noch präzisieren und
in Unterkategorien aufteilen. Wenn dann noch
ein Qualitätsmanagement dahinter steht, vervielfacht
sich der Aufwand entsprechend um das vielfache.
Jupp, bekannte und üblicherweise auftretende Fehlerfälle gehören
dokumentiert. Oder man schreibt eine Bedienanleitung derart, dass beim
Benutzen des Systems hinlänglich bekannte Fehler gar nicht erst
auftreten.
>Das wissen wir auch nicht, aber offensichtliche Sachen, wie "fehlende>externe Impule erzeugen folgende Meldung xyz" od. "wenn grüne LED blinkt>fehlt Wasser" ... würden den späteren Support wesentlich erleichtern.
Das gehört meiner Meinung nach in die Funktionsbeschreibung oder in die
Modulspezifikation.
>Nützlich wäre jedoch, einige>Hinweise zur Fehlersuche hinzuzufügen, da in x Jahren garantiert keiner>mehr da ist, den man fragen kann.
Fehlersuche im System oder Fehlersuche in Code??? Der Author drückt sich
leider nciht deutlich genug aus!
Rosa
Rosa-Kleidchen schrieb:> benutze UML. Damit hast Du nicht nur eine Highlevel-Doku, sondern auch> eine Basis für Deine Software, also klassisch Topdoen...> Rosa
Realitaetsabgleich:
Lass mich raten, du hast frisch die Softwaretechnik-Vorlesung an deiner
Uni bestanden? ;-)
UML ist alleine dazu da, um Tool-Hersteller und Berater mit Geld zu
versorgen - für den realen Alltagsgebrauch im agilen Umfeld ist es
völlig unbrauchbar.
Zumal Round-Trip-Engineering für Lebzeiten ein theoretischer Traum von
Powerpoint-Junkies sein wird.
>Lass mich raten, du hast frisch die Softwaretechnik-Vorlesung an deiner>Uni bestanden? ;-)
Nein, ich bin 17 Jahre raus..
>UML ist alleine dazu da, um Tool-Hersteller und Berater mit Geld zu>versorgen - für den realen Alltagsgebrauch im agilen Umfeld ist es>völlig unbrauchbar.
Nein, ich brauche das immer wieder, auch ohne Tool..
>Zumal Round-Trip-Engineering für Lebzeiten ein theoretischer Traum von>Powerpoint-Junkies sein wird.
Welcher Powerpoint-Junkie ist dir auf die Füße getreten?
Rosa
