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.
benutze UML. Damit hast Du nicht nur eine Highlevel-Doku, sondern auch eine Basis für Deine Software, also klassisch Topdoen... Rosa
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
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.