Dokumentation und Softwareentwicklung

[Dinomo]

Hallo!

Ich habe mal ein paar Fragen an die Entwickler unter Euch. Mich würde interessieren:
1. Wie dokumentiert Ihr Programmentwicklungen?
2. Wie macht Ihr das bei Entwicklungsteams?
3. Welche Dokumentationssysteme setzt Ihr ein?
4. Mit welchen SEU arbeitet Ihr und wie habt ihr evtl. die Dokumentationssysteme integriert?
5. Wie haltet Ihr die Dokumentation aktuell und konsistent?
6. Welche Probleme habt Ihr im Zusammenhang mit Programmentwicklungen und der Dokumentationserstellung?
7. Wie ist eure persönliche Bereitschaft und Einstellung zur Dokumentation?
8. Welche Probleme habt Ihr bei der Wartung und Weiterentwicklung von eigener oder fremder Software zu einem späteren Zeitpunkt mit der Dokumentation erlebt?

Es würde mich freuen, wenn Ihr euch die Zeit nehmen würdet, die Fragen zu beantworten.

Schonmal Danke im Voraus!

Dinomo

 

[below]

Du willst aber ganz schön viel wissen. Warum?

Ich dokumentiere im Code, wenn verlangt dann mit Doxygen oder Headerdoc.

Alex

 

[Master Pod]

Vielleicht bekommst du Konkurrenz


MP

 

[Dinomo]

Ist u.a. Bestandteil eines Referats im Wirtschaftsinformatik-Studium. Thema"Dokumentenverwaltung und Versionsmanagement in der Softwarepraxis".

 

[pepperbob]

1. Wie dokumentiert Ihr Programmentwicklungen?
2. Wie macht Ihr das bei Entwicklungsteams?
3. Welche Dokumentationssysteme setzt Ihr ein?
4. Mit welchen SEU arbeitet Ihr und wie habt ihr evtl. die Dokumentationssysteme integriert?
5. Wie haltet Ihr die Dokumentation aktuell und konsistent?
6. Welche Probleme habt Ihr im Zusammenhang mit Programmentwicklungen und der Dokumentationserstellung?
7. Wie ist eure persönliche Bereitschaft und Einstellung zur Dokumentation?
8. Welche Probleme habt Ihr bei der Wartung und Weiterentwicklung von eigener oder fremder Software zu einem späteren Zeitpunkt mit der Dokumentation erlebt?

Ad 1: Prinzipiell basiert ein Großteil der Doku i.d.R. aus Inline Dokumentation. Aufgrund des zeitlichen Drucks, ist es praktisch schwer eine korrekte Dokumentation nebenbei zu führen.
Ad 2: Jeder dokumentiert hier den Teil, den er gerade bearbeitet. Jeder Dokumentiert selbst, d.h. es gibt keine zentrale Sammelstelle.
Ad 3: Wir haben desletzt konzeptionell versucht (bzw. versuchen immernoch) die Dokumentation z.T. über ein Wiki abzubilden. Dies hat den Vorteil, dass dadurch automatisch eine gewisse Historisierung der Doku gegeben ist und die Wiki Syntax macht die Sache auch schnell zu formatieren und leicht leserlich (Querverweise, Links, Suchfunktion, Kategorisierung etc.)
Ad 4: Nichts besonderes. Prinzipiell ein Texteditor mit Syntaxhighlighting ohne Dokufunktion.
Ad 5: Theoretisch wird jede Änderung sofort Dokumentiert, d.h. die Doku sollte damit immer aktuell sein.
Ad 6: Problem 1 - Doku nimmt sehr viel Zeit ein. Problem 2 - Masse an "schneller" Inline Doku steigt damit. Problem 3 - Wiederauffinden v. Information erschwert
Ad 7: Doku ist langweilig und zeitraubend (obwohl mir die Wichtigkeit der Doku bewusst ist)
Ad 8: Durch mangelenden Umfang der Doku dauert die Einarbeit in fremdem Code enorm lang. Komplexe Programmkonstruktor können nur durch Zeile für Zeile lesen verstanden werden.

 

[BalkonSurfer]

Dokumentation ist überflüssig, da sich das eh keiner durchliest.
Inline-Doku ist kurz und schnell verfügbar, da man eh grad an der entsprechenden Codestelle ist.
Jede Methode bekommt einen Kommantarheader mit genauer Beschreibung was rein geht und was raus geht sowie eine Kurzbeschreibung des Sinns.

Im Code wird in 5-10er Blöcken beschrieben, was grad passiert. zb "Einlesen der Daten x und Verarbeitung durch Methodes x,y,z"

Dann noch ein paar Schimpfwörter in die Doku, damit es aussieht, als wäre das richtig harter Tobak was man da macht und ein paar mal im Code ne Gehaltserhöhung fordern

Das wars schon

 

[DeineMudda]

Huhu,

ich bin Dipl.-Ing. und bei einem der größten IT-Dienstleister dieses Landes als Consultant tätig.

Die Entwicklung erfolgt dort nach dem V-Modell, das bei IT-Projekten im Finanzsektor große Verbreitung hat.
Dort ist auch die Art und Weise der Dokumentation definiert.

Verwaltet wird das ganze (in diesem speziellen Fall) per CVS. Im V-Modell läuft das unter dem Thema "KM" (Konfigurationsmanagement) - dafür gibt es dann in jedem Projekt einen KM-Beauftragten, der z.B. für die Versionierung zuständig ist.

Normalerweise gilt: Ein Stück Software ohne Dokumentation ist wertlos - allerdings wird in der Praxis (besonders) oft an dieser Stelle eingespart.

Nachtrag: Vielleicht noch zur Größenordnung: Es werden Projekte >100MM abgewickelt.

 

[BalkonSurfer]

Huhu,

ich bin Dipl.-Ing. und bei einem der größten IT-Dienstleister dieses Landes als Consultant tätig.

Die Entwicklung erfolgt dort nach dem V-Modell, das bei IT-Projekten im Finanzsektor große Verbreitung hat.
Dort ist auch die Art und Weise der Dokumentation definiert.

Verwaltet wird das ganze (in diesem speziellen Fall) per CVS. Im V-Modell läuft das unter dem Thema "KM" (Konfigurationsmanagement) - dafür gibt es dann in jedem Projekt einen KM-Beauftragten, der z.B. für die Versionierung zuständig ist.

Normalerweise gilt: Ein Stück Software ohne Dokumentation ist wertlos - allerdings wird in der Praxis (besonders) oft an dieser Stelle eingespart.

Nachtrag: Vielleicht noch zur Größenordnung: Es werden Projekte >100MM abgewickelt.

Wenn das die Telekom sein sollte, weiß ich, dass ich das V-Modell nie nie nie anwenden werde
Wo ich grad beim Thema bin, gleich mal gucken, was die Telekom heute an der ALGII Software versaut hat

 

[firefoxuser]

Ich dokumentiere fast alles in den source files also à la
/*
* diese function macht diesund das
*/

außerdem werden sämtliche sachen nochmal ausführlicher in einer Lotus Notes datenbank gespeichert, die man sich dann mit dem team teilt ;-)

 

[DeineMudda]

Wenn das die Telekom sein sollte, weiß ich, dass ich das V-Modell nie nie nie anwenden werde
Wo ich grad beim Thema bin, gleich mal gucken, was die Telekom heute an der ALGII Software versaut hat

Die "Telekom" heißt T-Systems und: Nein, sie ist es nicht.

 

[BalkonSurfer]

Die "Telekom" heißt T-Systems und: Nein, sie ist es nicht.

Ich meinte mit Telekom auch den kompletten Verein - die bekommen durch die Bank alle nix hin.
BTW: Es gab bis vor kurzem auch nen IT-Dienstleister der Telekom, der nicht T-Systems hieß und quasi der T-Systems Konkurrenz gemacht hat.

 

[wegus]

sind wir hier in der bar ?

 

[Agmemon]

Q: Wie dokumentiert Ihr Programmentwicklungen?

A: Das kommt immer auf die bedürfnisse des Projektes an. Zumeist kommt bei mir eine Codedokumentation (inline), die den Code dokumentiert, und eine Projektdokumentation, für allgemeine Sachen, zum Einsatz.

Q: Wie macht Ihr das bei Entwicklungsteams?

A: jedes teammitglied ist selbst für das dokumentieren zuständig. Für grosse projekte kann es sein, dass es sogar Dokumentationsrichtlinien gibt. Bei der Projektdokumentation ist der Teamleister verantwortlich die Dokumentrationshappen der Mitglieder zusammen zu fügen, da vermutlich nur er en gesamten Überblick hat.

Q: Welche Dokumentationssysteme setzt Ihr ein?

A: Bei der inline Codedokumentation ist das von der Entwicklungssprache abhängig: JavaDoc bei Java, RDoc bei Ruby, Doxygen bei den anderen Sprachen wie C/C++, PHP, und so weiter. Für die Projektdokumentation nutze ich zunmeist DocBook, aber es kann auch Word sein, oder etwas in der Art.

Q: Mit welchen SEU arbeitet Ihr und wie habt ihr evtl. die Dokumentationssysteme integriert?

A: Unterschiedlich, und abhängig von der Sprache. Zumeist ist die Dokumentationserstellung einfach in das build-script integriert (make, rake, ant)

Q: Wie haltet Ihr die Dokumentation aktuell und konsistent?

A: Neu geschriebenen Code immer gleich dokumentieren.

Q: Welche Probleme habt Ihr im Zusammenhang mit Programmentwicklungen und der Dokumentationserstellung?

A: man macht mal schnell eine kleine Code-Änderung und vergisst es gleich zu dokumentieren.

Q: Wie ist eure persönliche Bereitschaft und Einstellung zur Dokumentation?

A: Notwendiges Übel. Aber wenn man hier Zeit investiert hat, freut man sich, wenn man den Code nach einem jahr mal wieder anfassen muss.

Q: Welche Probleme habt Ihr bei der Wartung und Weiterentwicklung von eigener oder fremder Software zu einem späteren Zeitpunkt mit der Dokumentation erlebt?

A: Oftmals wird im Library-Stil dokumentiert. Sprich eine Funktion bekommt eine Beschreibung, was sie macht, was rein geht und was raus geht. Das ist zwar nett, wenn man diese Funktionen nur benutzen muss, aber wenn Änderungen in der Funktion nötig sind, sitzt man stunden da, um zu versuchen den Algorithmus nachzuvollziehen. Und sind keine UnitTests vorhanden, hat man oft Probleme die Pre- und PostConditions zu bestimmen.

 

[Keek]

Hallo zusammen,

ich möchte hiermit noch einmal dieses uralte Thema hervorkramen.

Ich werde bald einen neuen MS SQL Server entwickeln und dann eine bestehende MS Access Datenbank in dieselbige migrieren müssen.

Ebenfalls muss eine Dokumentation darüber angefertigt werden. Jedoch bin ich da noch recht hilflos. Im Studium wird zwar regelmäßig die Relevanz einer Dokumentation aufgegriffen, aber nicht erklärt wie man sie richtig umsetzt.

Wie dokumentiert ihr (mal abgesehen von InLine Dokumentation) bei euren Projekten?

Wird jeder einzelne Schritt dokumentiert bzw. wie Detailreich ist eure Dokumentation?
Wie dokumentiert ihr aufgetretene und gelöste Probleme?
Wie strukturiert ihr eure Dokumentation? Insbesondere wenn ihr mit Word dokumentiert - oder nutzt ihr extra Software?

Leider kann ich euch noch nicht viel mehr über das Projekt sagen, da ich selbst noch nicht mehr weiß ;-)
Bin über jegliche Tipps und Hinweise dankbar...

Grüße
Keek.
edit: Ach, ich sollte der Vollständigkeit halber vielleicht noch erwähnen das es sich um keine Dokumentation/Handbuch für den Endanwender handeln soll ;-)

Abschließend noch ein Post den ich aus einem anderen Thread habe...

Ware Worte.
In der DB-Entwicklung gehen schonmal 60% der Zeit für die Normalisierung drauf und Gnade Dir Gott, wenn Du da nicht ordentlich bist...
Dokumentieren ist das A und O und wer beschreiben kann, um was es aktuell geht, der weiss auch worum es geht.
Ich kenne einige begnadete VBA-Menschen, die Null umgesetzt haben, weil sie sich endlos in der Schönheit der Lösung eines Teilaspektes verzettelt haben. An der fehlenden Doku oder auch nur am fehlenden Tagesbericht sieht man dann, dass man einschreiten muss.

 

[pepperbob]

Also ca. 9 Jahre und etliche Lehrstunden nach meinem letzten Post würde ich deine Fragen mal so beantworten:

> Wie dokumentiert ihr (mal abgesehen von InLine Dokumentation) bei euren Projekten?
> Wird jeder einzelne Schritt dokumentiert bzw. wie Detailreich ist eure Dokumentation?

Inline Dokumentation ist die absolute Ausnahme, gerade was Programm-Code angeht - denn das Zeug ist i.d.R. relativ veraltet und wird weder gelesen noch weitergepflegt; es taucht gern mal bei APIs auf, um erwartetes Verhalten zu definieren aber solange wir kein Framework bauen, womit Software geschrieben wird, ist es zu vermeiden.

Software ist weitestgehend mit automatisierten Tests abgedeckt, das sind sowohl Unit Tests als auch Integrations- und Smoketests. Jede Code-Änderung referenziert im Commit-Log ein zugehöriges Ticket und wird einem Review unterzogen, d.h. es gibt mindestens 2-3 Leute, die bei Code-Änderungen / Neuentwicklungen mit im Boot sitzen.

Software Tests, Releases und Deployments auf diverse Systeme Test/Staging/Produktion sind weitgehend automatisiert und funktionieren für die verschiedenen Projekte immer nach dem gleichen Schema.

Warum schreibe ich den ganzen Kram? Die Idee dahinter ist, dass Entwicklungsprozesse, -Methoden und -Tools Zusammenhänge verknüpfen und damit einen großen Teil an Dokumentation und umfangreicher Erklärung, welche in der Vergangenheit erstellt wurde einfach obsolet machen; Release und Deployment Prozesse sind weitgehend standardisiert und vereinheitlicht. Wir arbeiten häufig mit externen Dienstleistern zusammen und diese werden in die definierten Prozesse mit eingebunden, so dass auch auf dieser Schiene wenig Lücken entstehen auch ohne Prosa-Dokumentation anfertigen zu müssen.

> Wie dokumentiert ihr aufgetretene und gelöste Probleme?
> Wie strukturiert ihr eure Dokumentation? Insbesondere wenn ihr mit Word dokumentiert - oder nutzt ihr extra Software?

Was die Toolchain angeht verwenden wir Confluence, Jira und Stash (alles von Atlassian) - das deckt so ziemlich jeden Use-Case ab, um kollaborativ an den diversen Enden und Ecken der Software-Entwicklung zu arbeiten. Es gibt natürlich die guten alte Word Dokumente (und Excel Tabellen), aber die Beobachtung ist jedesmal, dass in kürzester Zeit Kopien in der freien Wildbahn sind und Versionen entstehen bei denen dann keiner mehr weiß, was da jetzt eigentlich aktuell ist. Ich kann dem noch nichtmal was abgewinnen, wenn ich allein meine Notizen mache.

HowTo Artikel, Übersichten, Projekt-Vorstellungen, Konzepte, Prozesse, Ansprechpartner usw. schreiben wir im Confluence auf - das geht mal strukturierter, mal weniger strukturiert und ist sicher verbesserungswürdig - aber es gibt ja eine Volltext-Suche insofern stehen die Chancen ganz gut Dinge wieder zu finden.

Aufgaben & Todos werden über Jira gepflegt, Code-Änderungen und Code Reviews sind in Stash nachvollziehbar - da dieses Dreigestirn der Toolchain komplett miteinander vernetzt ist, gibt es natürlich vom Confluence direkte Verknüpfungen auf Jira Tickets (vice versa), aus den Tickets wiederum werden die Code Reviews und Commits referenziert und von dort sind Links zum CI-Tool (Jenkins) gesetzt, wo jeder Build im Detail angeschaut werden kann, wenn benötigt - so findet man aus diversen Einstiegspunkten im Optimalfall alles was man braucht. Natürlich kann ich Leuten, Themen oder Code "folgen" und bleibe so auch up-to-date.

Dazu ist jetzt zu erwähnen, dass unser Kern-Team aus über 20 Leuten besteht und es dabei einen entsprechend hohen Bedarf an Kommunikation geben muss, der durch besagte Tools vereinfacht wird.

 

[Keek]

Hallo pepperbob,

wow - das sich jemand meldet der vor 9 Jahren hier schon gepostet hat und nicht regelmäßig im Forum schreibt hätte ich nicht erwartet.
Erstmal dankeschön für deine Antwort.

Wenn man deine beiden Beiträge vergleicht kann man ja sagen das sich da in den letzten Jahren bei dir jede Menge weiterentwickelt hat.
So sind eure Prozesse ja schon ziemlich professionalisiert und für mich vermutlich überdimensioniert. Dazu muss ich sagen das ich alleine am
oben genannten Projekt arbeiten werde und die Dokumentation auch hauptsächlich für die Vermeidung von "KnowHow"-Verlust erstellt werden wird.
Das ich nicht länger dort arbeiten werde steht quasi fest

Von deinen genannten Tools kenne ich durch eigene Benutzung lediglich das Stash-ähnliche Bitbucket (da sehe ich gerade, dass das auch von Atlassin ist). Das regelmäßige comitten von Codeupdates ist ja auch keine große Tat.
Werde mir die drei aus Interesse aber auch mal näher ansehen, denke aber das ist etwas 'overpowered'. Du sprichst ja auch bereits die Teamgröße von ~20 Leuten an.

Dein Argument, den Entwicklungsprozess bereits so zu gestalten das die mühsame Dokumentation größtenteils wegfällt, kann ich gut nachvollziehen. Wäre da nicht der große Initiale Aufwand ein solches System übergreifend zu etablieren.


Gibt es hier noch Entwickler die die Dokumentation weniger professionell angehen? Vielleicht auch alleine oder in einem kleinen Team arbeiten?!