Software Design Dokument erstellen

> Es gibt vom Arbeitgeber jedoch keine wirklich konkreten Vorgaben
> wie so ein Dokument auszusehen hat und was es genau enthalten soll.

Doch solche Vorgaben gibt es, sogar als Standard (ANSI/IEEE Std 
1016-1998)
Falls Du bei deiner Ausbildung diesbezüglich verschlafen hast, bleibt 
dir immer noch in der WP nachzuschlagen und geeignete Literatur zu 
ordern:

https://en.wikipedia.org/wiki/Software_design_description

Fast track to /dev/null schrieb:
> Doch solche Vorgaben gibt es, sogar als Standard (ANSI/IEEE Std
> 1016-1998)

Dieses Dokument gibt aber überhaupt gar keine Beispiele. Nach der 
Lektüre ist man nicht sehr viel schlauer als vorher. Deshalb auch meine 
Frage:

> Gibt es existierende Beispiele für ein Dokument, das für gut befunden
wurde?

Die deutsche Version von dem verlinkten Artikel zählt doch schon recht 
gut nachvollziehbar auf was ein SDD beinhalten sollte.

Das SDD wird der Bauplan für das Ding Software welches die Anforderungen 
des Kunden erfüllen soll.

Es müssen also die Anforderungen und deren Umsetzung im SDD erkennbar 
werden.

Der Leser des SDD wird somit erst einen Überblick über Anforderungen und 
Lösungsansätze vorfinden und dann im Detail erkennen können wie es die 
Software hin bekommt das jede der Anforderungen erfüllt sein wird.

Das Wort Design steht dabei doch für die realisierte Art und Weise wie 
die Software das letzt endlich machen wird.

Der Autor des SDD wird also die gewünschte Software erst grob planen um 
dann die einzelne Komponenten davon feiner zu strukturieren.


Entweder Du kannst programmieren und somit die Aufgabe lösen und auch 
den Weg dorthin nieder schreiben (was dann quasi im SDD mündet) oder Du 
wirst weder das eine noch das andere hin bekommen.

SDD ohne Kontext ist ein Buzzword.

Wie es aussieht, hängt davon ab, für wen es ist (Management Kunde, 
Programmierer, QS, Marketing, ...), In welchem Kontext es steht (gibt es 
gesonderte Dokumente für Anforderungen, Randbedingungen, Realisierung, 
Test, Vorgehensmodell). Und meist auch der Projektumfang (100 Leute ein 
Jahr oder ein Freelancer 6 Wochen).

Wenn es Neuland, kommt vermutlich hinzu, dass niemand übliche 
Beschreibungssprachen (UML, stateflow) lesen kann.

Software Designer schrieb:
> Fast track to /dev/null schrieb:
>> Doch solche Vorgaben gibt es, sogar als Standard (ANSI/IEEE Std
>> 1016-1998)
>
> Dieses Dokument gibt aber überhaupt gar keine Beispiele. Nach der
> Lektüre ist man nicht sehr viel schlauer als vorher. Deshalb auch meine
> Frage:
>
>> Gibt es existierende Beispiele für ein Dokument, das für gut befunden
> wurde?

Ehrlich, vergiss das mit den Beispielen schleunigst, Beispiele sind was 
fürs Kinderalter, wenn das Verständniss für den Sinn und Zweck 
'dahinter'  noch weitgehend fehlt. Nach Beispielen lernen ist Nachäffen: 
Der Form nach richtig aber der Inhalt ist inkonsistent und viel mit 
Widersprüchen. Die 'Krönung' der Arbeit nach Beispielen ist Cargo-Kult 
https://schulesocialmedia.com/2016/07/05/die-zwiespaeltigen-cargo-kulte/

Leider denken viele noch, wenn etwas Dokument genannt wird (obwohl es 
eigentlich description heisst) das wäre sowas wie ein Formblatt das man 
stupide mit Daten füllt.

wie hier schon gesagt, SDD bedeudet:
> ... die Aufgabe lösen und auch
> den Weg dorthin nieder schreiben (was dann quasi im SDD mündet)

Doxygen, der defacto Standard für Software Dokumentation

Wir verwenden in der Firma ein paar, auf unsere Arbeitsweise 
zugeschnittenen, Dokumente zum Dokumentieren des Software Designs:

- Requirements: Excelliste mit Requirements und erklärenden Kommentaren. 
Die sollte auch bei Weiterentwicklungen entsprechend gepflegt sein und 
vollständig. Sowohl funktional als auch non-funktional Requirements.
Am wichtigsten für das Management zur Kommunikation mit dem 
Entwicklungsteam, da dann das Entwicklungsteam sagen kann, wir haben 
alle Requirements erfüllt.

- "UML light": Wir nutzen fast ausschließlich Visio dafür.
   * Modul- und Datenflussdiagramm: Alle "Module" (egal wie ihr 
programmiert, ihr werdet ja irgendwie Module haben, entweder als 
MVC-Pattern bei GUIs oder sonstige Frameworks) und deren Datenflüsse 
zueinander. Aus dem Datenflussdiagramm gibt es eine Verlinkungen zur 
Interfacedefinition.
   * Zustandsdiagramme: Welche Zustände haben die Module und wer startet 
welches Modul. Wichtig in verteilten Systemen und wenn man, so wie wir, 
mit Hardware spricht. Wichtig: Hier sollen äußere Zustände dokumentiert 
werden, die Einfluss auf andere Module haben (z.B. Hardware ist in einem 
Wait-State, da eine Bewegung gestartet wurde und die Hardware daher 
aktuell keine neuen Befehle empfängt).

- Interfacedokumentation: Meist schon direkt Code (z.B. bei protobuf), 
aber in einem eigenen Repo am GIT-Server abgelegt und verlinkt mit dem 
Datenflussdiagramm. Falls man nicht direkt Code dort ablegen kann, muss 
der Entwickler es leider textuell beschreiben z.B. bei Simulinkmodellen.

- Codedokumentation: Unterste Ebene um API-Calls usw. zu dokumentieren. 
z.B. mit Doxygen.

Wenn man es gut in den Entwicklungsprozess integriert, ist es kein 
zusätzlicher Aufwand, sondern ein wichtiger Teil der 
Gesamtdokumentation.
Interfaces und Zustände muss man sich beim Programmieren (oder besser: 
davor) sowieso überlegen.
Klar ist aber: Sowas muss vor und während der Entwicklung passieren. Die 
Dokumente müssen immer den wahren Stand der Software widerspiegeln. Auf 
keinen Fall, dürfen diese Dokumente erst danach erstellt werden oder die 
Dokumente als unverändliches Gesetz angesehen werden.

Seitdem wir so arbeiten, haben wir nur positive Rückmeldungen unserer 
Softwareentwickler bekommen.

Hannes J. schrieb:
> Wir schreiben das Jahr 2020 und es gibt immer noch Software-Buden in
> denen eine Design-Dokumentation Neuland ist?!? Bitte nicht die Ausrede
> "wir machen eigentlich ...". Wenn euer "eigentlich" Software braucht
> dann seid ihr eine Software-Bude.

Was soll denn der Rant. Wir wissen nicht, ob sie gerade mit sw anfangen, 
was der TO macht, wie sw bisher dort aussieht. Und dass sw besser wird, 
wenn man prozessgläubige Fremde daran lässt, ist auch nicht sicher.

Ohne jeden konkreten Bezug verordnete Prozesse dienen nur den 
Bedenkenträgen, die dann so oder so fein raus sind

Der TO hat gefragt. Gut. Ein erster Schritt. Er ist auf ein Buzzword 
reingefallen. Kann passieren. Wenn er weitere Fragen hat, gut, wenn 
nicht: auch.

A. S. schrieb:
> Wie es aussieht, hängt davon ab, für wen es ist (Management Kunde,
> Programmierer, QS, Marketing, ...), In welchem Kontext es steht (gibt es
> gesonderte Dokumente für Anforderungen, Randbedingungen, Realisierung,
> Test, Vorgehensmodell). Und meist auch der Projektumfang (100 Leute ein
> Jahr oder ein Freelancer 6 Wochen).

Für wen:
Hauptsächlich QS, und für die Programmierer und SW-Tester.

Es existieren Dokumente mit den SW-Anforderungen. Auf dieser Basis soll 
as SW-Design erstellt werden.

Umfang: Ich schätze mal zwei Mannjahre insgesamt.

C. A. Rotwang schrieb:
> Ehrlich, vergiss das mit den Beispielen schleunigst, Beispiele sind was
> fürs Kinderalter, wenn das Verständniss für den Sinn und Zweck
> 'dahinter'  noch weitgehend fehlt. Nach Beispielen lernen ist Nachäffen

Wenn man etwas Gutes "nachäfft" und damit selbst zu einem guten Ergebnis 
kommt - was ist dann daran bitte auszusetzen? Im Beruf zählt immer noch 
zuallererst das Ergebnis. Wie man es erreicht hat, interessiert im 
Nachhinein keine Sau mehr (eigene Erfahrung).

Hannes J. schrieb:
> Wir schreiben das Jahr 2020 und es gibt immer noch Software-Buden in
> denen eine Design-Dokumentation Neuland ist?!?

Mit Sicherheit ist das so. Ja.

Wenn es in Eurer "Bude" herovrragend gute Dokumente in dem Bereich gibt, 
dann zeig doch einfach mal eins :-)

> Ich vermute mal, an die Nützlichkeit einer Design-Dokumentation glaubt
> in der Firma sowieso niemand, sonst hätte man schon längst einen
> (zumindest firmeninternen) Standard.

Das wir den nicht haben finde ich ja selbst auch unverständlich. Aber 
was es an Vorgaben nicht gibt, kann ich halt nicht herbeizaubern.

> Schlussfolgerung: Weil es sowieso niemanden in der Firma interessiert
> ist es scheiß-egal was in der Software Design-Dokumentation steht. Sie
> muss nur gut aussehen, nicht gut sein.

Am Ende könnte es fast darauf hinauslaufen. So nach dem Motto 
"Hauptsache es existiert ein Dokument", damit irgendein Prozesshansel 
befriedigt ist.

> Zweite Vermutung, es wird auch keine Entwicklungsmethode verwendet,
> außer der Helden-Methode: Einsamer Held mit autistischen Tendenzen hackt
> irgend einen Müll zusammen und lässt sich dafür feiern? Ohne
> Versionskontrolle, ohne Backups, so ganz privat auf seinem eigenen PC?
> Eben ohne jegliche Art von Kommunikation.

Es gibt ein Code Repository, es gibt Anforderungsdokumente, es gibt eine 
Test-Abteilung.

> Nur hast du nicht nach Nützlichkeit gefragt, sondern ohne weiteren
> Kontext nur nach irgend etwas, was man als "für gut befindet".

Gibt es denn darüber keinen Konsens? Wenn es den eh nicht geben sollte, 
dann kann man diese Aufgabe wohl weder besonders gut noch besonders 
schlecht erledigen.

Software Designer schrieb:
> Es existieren Dokumente mit den SW-Anforderungen. Auf dieser Basis soll
> as SW-Design erstellt werden.

Das ist doch ein Anfang. Nimm die Anforderungen, und schreibe (mit dem 
SW-Architekten oder ersten SW-Entwickler) wie und womit diese 
Anforderungen realisiert werden und wie jede einzelne davon getestet 
werden kann. Du wirst schwammige Anforderungen haben. Wandle die in 
konkrete. Eine Anforderung ist nur dann eine, wenn sie konkret getestet 
werden kann.

Schreibe, welche Frameworks zum Einsatz kommen (gcc, freeRTOS, cmake, 
...) Mache 5 bis 50 Blöcke ähnlichen Umfangs (Displaytreiber, Menü, HAL, 
mp3-encoding, ...) und ordne die auf einem Blatt an, mit den groben 
Beziehungen untereinander. Z.b. die Blöcke den verschiedenen Gruppen 
zuordnen und auf welche Interfaces sie zugreifen.

Liste mitgeltende Unterlagen auf, die ihr verwendet. Vielleicht MISRA, 
vielleicht Coderichtlinien.

Schreibe dabei, wer, wann was warum entschieden hat.

Aber mache das alles nur und erst, wenn Du verstanden hast, wofür das 
gut ist, und nur so, dass es Dir hilft, Deine Gedanken und Infos zu 
ordnen.

Software Designer schrieb:
> C. A. Rotwang schrieb:
>> Ehrlich, vergiss das mit den Beispielen schleunigst, Beispiele sind was
>> fürs Kinderalter, wenn das Verständniss für den Sinn und Zweck
>> 'dahinter'  noch weitgehend fehlt. Nach Beispielen lernen ist Nachäffen
>
> Wenn man etwas Gutes "nachäfft" und damit selbst zu einem guten Ergebnis
> kommt - was ist dann daran bitte auszusetzen?

Eben das das Ergebnis erreichen im Falle des Nachäffens ohne Verständnis 
Glückssache ist (wenn überhaupt, in den meisten Fällen ist es eher reine 
"Beschäftigungstherapie")

> Im Beruf zählt immer noch
> zuallererst das Ergebnis.

Solanges es zur Aufgabe passt und die Qualität stimmt.
Die Aufgabe ist ein ganz konkretes Software Design verständlich zu 
beschreiben. Und da hilft es wenig die Beschreibung einer willkürlich 
anderen Software auf die eigene "hinzufrimmeln". So als ob einer die 
Beschreibung eines Flugzeuges nimmt (hat zwei Flügel, Schwanz und Räder 
und transportiert Hunderte Passagiere und tonnenweise Cargo von A und B) 
und daraus die Beschreibung eines Auto macht -> (hat keine Flügel, 
keinen Schwanz aber Räder und transportiert wenige Passagiere und wenig 
Cargo von C und D) und denkt er ist fertig. So wie die Eingeborenen in 
den Südseeinseln, die meinten es genügt mit Strohpuppen ein Airfield zu 
imitieren und dann kommt das Cargo eingeflogen ...

wie drüber gesagt:
> "Aber mache das alles nur und erst, wenn Du verstanden hast, wofür das
> gut ist, und nur so, dass es Dir hilft, Deine Gedanken und Infos zu
> ordnen."

Über der SDD steht die SRS.
Daraus leiden sich deine Requirements ab die du dann in der SDD 
beschreibst und verlinkst.
Wenn Du einen SDP hast, könntest du darin Hinweise zur Umsetzung finden.
Freddy

Mach einfach Scrum. Dann brauchst du solche Dokumente nicht.

vorschlager schrieb:
> Mach einfach Scrum. Dann brauchst du solche Dokumente nicht.

Brauchen tust Du es da auch. Es ist nur auf zig Schnipsel verteilt und 
flüssig wie ein Wackelpudding.

SRS/SDD und Scrum wiedersprechen sind nicht.
Ganz im Gegenteil, wir setzen Scrum/Agile ein um die Entwicklung zu 
koordinieren und da wir unter extremen Zeitdruck teilweise die 
Spezifikationen auf unterer Ebene (wozu auch die SRS gehört) noch nicht 
komplett durchdefiniert sind.
Die SRS und SDD stehen im V-Model auf zwei Pfaden und sind durch die 
Verfikation verknüpft.
Ich bin kein Freund vom Dokumentenurwald, insbesondere wenn man an die 
Dokumente auf Systemebene oder den Zwischenebenen denkt. Zumal selbst 
bei mittelgroßen Projekten häufig der Architekt und der Entwickler die 
gleiche Person sind oder eng zusammenarbeiten.
Aber selbst in der eigenen Firma gibt es Abteilungen die mehr oder 
weniger als Entwicklungsdienstleister arbeiten und unterschiedliche 
Projekte gleichzeitig bearbeiten.  Da sind diese Dokumente schon 
sinnvoll und dienen auch als Leistungsnachweis gegenüber der 
Projektleitung, wenn die Requirements aus der SRS in der SDD abgebildet 
sind und hiernach geprüft wurden.
Das hat uns schon ein paarmal davor bewahrt den schwarzen Peter 
zugeschoben zu bekommen, denn die Implementation entsprach der 
Sepzifikation.
Das bringt das Projekt nicht weiter und ist ärgerlich, aber genau 
deswegen versucht man ja die Entwicklung agil zu begleiten. Damit genau 
das nicht passiert und keiner sich zurücklehnt bis alle Dokumente fertig 
sind.
Zumal auch das V-Model eine Iteration zulässt, sprich eine Rückkehr zur 
Architekturphase.  Manchmal stellt sich erst bei der Implementierung 
heraus, dass die Architektur zu kompliziert ist und da ist frühes 
Feedback und Änderungswünsche am besten per Scrum/Agile zu steuern.

olw schrieb:
> Sowas muss vor und während der Entwicklung passieren. Die
> Dokumente müssen immer den wahren Stand der Software widerspiegeln. Auf
> keinen Fall, dürfen diese Dokumente erst danach erstellt werden oder die
> Dokumente als unverändliches Gesetz angesehen werden.
>
> Seitdem wir so arbeiten, haben wir nur positive Rückmeldungen unserer
> Softwareentwickler bekommen.

Wow..
vollständiges FLussdiagram während der Entwicklung...
jede Änderung im call nochmal die doku aktualisieren, damit 20min später 
eine neue änderung eine neue aktualisierung nachsich zieht.
Verzeih, aber das klingt mir nur bei grösseren Entwicklungsteams für 
sinnvoll;
oder falls die Entwickler in räumlicher (oder kommunikativer) Distanz 
arbeiten.

Bei KleinKlitschen (vier Mann ein Schreibtisch) kannste temporäre 
Änderungen
die ggf nicht von Dauer sind besser über den Rand der Kaffeetasse 
bellen,
und erst die Doku aktualisieren wenn man sich endgültig festgelegt hat 
(für jene softwareversion)
also doch NACHHER (okay ein blockcomment als "info" ist dufte.. aber 
mehr ist in kleineren gruppen eher unsinn!)

'sid

sid schrieb:
> olw schrieb:
>> Sowas muss vor und während der Entwicklung passieren. Die
>> Dokumente müssen immer den wahren Stand der Software widerspiegeln. Auf
>> keinen Fall, dürfen diese Dokumente erst danach erstellt werden oder die
>> Dokumente als unverändliches Gesetz angesehen werden.


> vollständiges FLussdiagram während der Entwicklung...

Ich glaube davon redet nur der, der es absichtlich missversteht.Eeine 
Designbeschreibung ist eine Schnittstellenbeschreibung, kein 
vollständiges Flussdiagramm

> jede Änderung im call nochmal die doku aktualisieren, damit 20min später
> eine neue änderung eine neue aktualisierung nachsich zieht.

Völlig verdreht, es geht nicht um das Dokument nach der Implementierung, 
sondern um das Dokument das vor der Implementierung erstellt wird, 
sozusagen 'der Plan' den jedes 'Codierschwein' verfolgt während es durch 
die Tastatur 'pflügt'.

> Verzeih, aber das klingt mir nur bei grösseren Entwicklungsteams für
> sinnvoll;
> ..
> und erst die Doku aktualisieren wenn man sich endgültig festgelegt hat
> (für jene softwareversion)

Nein man legt sich vorher fest was man programmieren will. Wenn sich das 
Ergebnis als Bullshit erweist, dann wird das so im Report festgehalten 
und die SDD geändert, dann die Ändrung implementiert. Das ist ein 
geringer Aufwand, wenn nicht sogar zeitsparend, den nicht selten stellt 
man beim beschreiben dessen was man vorhat fest, welchen 'Rattenschwanz' 
an weiteren Änderungen das mit sich zieht und lässt es dann.

Ein weiterer Aspekt ist der, der Kommunikation. Auch die Information, 
was versucht und als untauglich verworfen wurde, muss jederzeit present 
sein, nicht nur im Team, sondern auch dem 'Codierschwein' selbst - Jahre 
nach der Änderung.

Dokumente aka schriftlich fixierte Beschreibungen sind eine Form der 
Kommunikation unter vielen.
Improvisierenderweise kann man ein 10-minutiges StandUp Meeting täglich 
früh führen, das schafft einen minimale Rahmen planvoll mit der 
täglichen Arbeitszeit umzugehen.

https://www.heise.de/tp/features/30-Sekunden-Redezeit-3436273.html
https://agilescrumgroup.de/daily-stand-up-meeting/

Wobei das kein Ersatz für die SSD ist, sondern eine Methode den 
Informationsfluß und -Konsistenz zwischen den Dokumenten und deren 
'Umsetzer' zu initiieren und lebendig zu halten.

C. A. Rotwang schrieb:
> Improvisierenderweise kann man ein 10-minutiges StandUp Meeting täglich
> früh führen, das schafft einen minimale Rahmen planvoll mit der
> täglichen Arbeitszeit umzugehen.

Das geht heute wohl nur in Start-ups mit 60h-woche. Welcher 
SW-entwickler arbeitet heute ohne Gleitzeit. Maximal eine Zeit kurz vor 
oder nach dem Mittag.

A. S. schrieb:
> C. A. Rotwang schrieb:
>> Improvisierenderweise kann man ein 10-minutiges StandUp Meeting täglich
>> früh führen, das schafft einen minimale Rahmen planvoll mit der
>> täglichen Arbeitszeit umzugehen.
>
> Das geht heute wohl nur in Start-ups mit 60h-woche. Welcher
> SW-entwickler arbeitet heute ohne Gleitzeit. Maximal eine Zeit kurz vor
> oder nach dem Mittag.

Gleitzeit als Meetinghindernis, ja so kann man es auch sehen. Lange Zeit 
hieß es, der Exitus der Raucherpausen hat die teaminterne Kommunikation 
nachhaltig beschädigt ...

Vielleicht mal nach Schweden schauen, da hat es die obligatorische fika 
- die Kaffeepause (auch im Office):
https://blog.trello.com/de/fika-schwedisch-kaffeepause
https://www.virgin.com/entrepreneur/can-introducing-swedish-concept-fika-improve-happiness-work

C. A. Rotwang schrieb:
> jedes 'Codierschwein' verfolgt während es durch
> die Tastatur 'pflügt'

C. A. Rotwang schrieb:
> dem 'Codierschwein' selbst

Diese Ausdrucksweise muss man unbedingt intus haben, wenn
man erfolgreicher Softwarearchitekt / Projektleiter werden will.

Josef schrieb:
> Diese Ausdrucksweise muss man unbedingt intus haben, wenn
> man erfolgreicher Softwarearchitekt / Projektleiter werden will.

Josef schrieb:
> C. A. Rotwang schrieb:
>> jedes 'Codierschwein' verfolgt während es durch
>> die Tastatur 'pflügt'
>
> C. A. Rotwang schrieb:
>> dem 'Codierschwein' selbst
>
> Diese Ausdrucksweise muss man unbedingt intus haben, wenn
> man erfolgreicher Softwarearchitekt / Projektleiter werden will.

Njein, da sollte man die englischen Begriffe drauf haben, also 'code 
monkey' oder auch 'Code cowboy'. Und man sollte nicht nur den Begriff 
sondern auch seine Bedeutung kennen:

code monkey ... a computer programmer who isn't actually involved in any 
aspect of conceptual or design work, but simply writes code (to 
specifications given).