AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren
Thema durchsuchen
Ansicht
Themen-Optionen

Was gehört alles in eine richtige Dokumentation?

Ein Thema von Back2Code · begonnen am 18. Nov 2013 · letzter Beitrag vom 14. Dez 2013
Antwort Antwort
Seite 2 von 4     12 34      
r2c2

Registriert seit: 9. Mai 2005
Ort: Nordbaden
925 Beiträge
 
#11

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 18. Nov 2013, 21:36
Die Antwort auf alle Fragen in der Softwareentwicklung: "It depends" bzw. "kommt drauf an".

Zu Dokumentation hat fast jeder eine Meinung. Und je nachdem, wen man fragt wird man *sehr* unterschiedliche Antworten erhalten. Fakt ist: Eine pauschale Antwort gibt es nicht.

Demnach musst du die Frage für dich beantworten. Dabei solltest du folgendes bedenken:
- Wer soll die Doku lesen? Und was erwarten diese? Doku ist mit Sicherheit falsch, wenn sie an den Anforderungen der Stakeholder vorbei geht. Und das kann je nach Projekt sehr unterschiedlich sein.
- Doku ist kein Selbstzweck. Je mehr du davon hast, desto aufwendiger ist es, sie zu pflegen. Und veraltete Doku ist i.d.R. schlechter als gar keine.
- Je näher die Doku am Code ist (rein räumlich gesehen), desto wahrscheinlicher ist, dass sie gepflegt wird. Selbsterklärender Code > Kommentare im Code > Doku mitversioniert im selben Repository > Doku außerhalb des Repos > Doku auf Paper.
- Doku, die keine neue Info hat, ist kontraproduktiv. Doku zu dem Konstruktor, die sagt "Create erzeugt ein neues Objekt" oder noch besser "Konstruktor der Klasse" ist sinnloses Gebabbel und sollte man unterlassen.
- Je mehr Stakeholder du hast, desto mehr Doku ist nötig. Schreibst du ne API für hunderte anderer Entwickler, brauchst du mehr Doku, als wenn du der einzige bist, der das unter die Finger kriegt. Wenn sich das Entwicklerteam ständig ändert, brauchst du mehr Doku, als wenn du ein festes, unveränderliches Team hast.
- Je mehr sich der Code ändert, desto schneller veraltet Doku und desto weniger solltest du haben. Abstrakte Basisklassen musst du eher beschreiben als temporäre Implementierungen, die beim nächsten Refactoring eh wieder wegfallen. Ebenso ist es sinnvoller, die grobe Architektur zu dokumentieren (weil die sich nur langsam ändert), als irgendwelche privaten Methoden, die eh ständig umgeschrieben werden. Dokumentiere Abstraktes und Allgemeines eher als konkretes.
- Doku macht nur Sinn, wenn sie auch gelesen wird. Wenn sie zu detalliert ist und niemand den Detailgrad braucht, ist das vergeudete Zeit. Diagramme sind gut. Denn damit kann man Zusammenhänge übersichtlich zeigen, die man im Code nie sehen würde, weil man im Code quasi immer mit der Lupe vor nem monumentalen Wandteppich steht. Diagramme, die aber nicht übersichtlich sind, sind wertlos.
- Wenn du wissen willst, was gute Doku ist, guck dir schlechte an.
- Besser noch: frag die Stakeholder, die die Doku lesen sollen nach Beispielen für gute und schlechte Doku. Frag sie, was sioe ganz konkret brauchen und erwarten. Frag sie, was sie haben wollen und wie sie die Doku benutzen würden. Ganz konkret die Personen, die das betrifft. Wir hier können nur Anhaltspunkte liefern und ggf. aus dem Nähkästchen plaudern. Aber wir können hier keine Abschließende Antwort liefern, weil wir dein Projekt nicht kennen.
- ...

mfg

Christian
Kaum macht man's richtig, schon klappts!
  Mit Zitat antworten Zitat
Benutzerbild von Bernhard Geyer
Bernhard Geyer

Registriert seit: 13. Aug 2002
17.197 Beiträge
 
Delphi 10.4 Sydney
 
#12

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 18. Nov 2013, 23:10
Die Antwort auf alle Fragen in der Softwareentwicklung: "It depends" bzw. "kommt drauf an".
...
...
...
Besser hätte man es nicht schreiben können
Windows Vista - Eine neue Erfahrung in Fehlern.
  Mit Zitat antworten Zitat
delfox

Registriert seit: 18. Nov 2013
8 Beiträge
 
#13

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 20. Nov 2013, 19:08
Hi!

Oft schon die Basics - Zugangsdaten und bei externen die Ansprechpartner. Welche Versionen kamen zum Kunden. Welche Versionen sind wo archiviert. Dann der Quellcode. Wenn eine Datenbank genutzt wird, dann ein ER Diagramm. Welcher Aufwand wurde betrieben, damit man bei weiteren Projekten schauen kann, ob man im Budget war.
  Mit Zitat antworten Zitat
Klaus01

Registriert seit: 30. Nov 2005
Ort: München
5.768 Beiträge
 
Delphi 10.4 Sydney
 
#14

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 20. Nov 2013, 19:42
Laut Uncle Bob ist eine Software ausreichend dokumentiert
wenn zu allen Methoden/Funktionen Testfälle/Unit-Tests vorliegen.

Grüße
Klaus
Klaus
  Mit Zitat antworten Zitat
Benutzerbild von blondervolker
blondervolker

Registriert seit: 14. Sep 2010
Ort: Bei: Leeeiipzzhhh
381 Beiträge
 
Delphi XE2 Architect
 
#15

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 20. Nov 2013, 21:50
Such einfach bei den "GROßEN"...
Die haben verschiedene Textepassagen meistens... per "RA" überprüfen lassen...
www.bewerbungsmaker.de
  Mit Zitat antworten Zitat
Benutzerbild von DeddyH
DeddyH

Registriert seit: 17. Sep 2006
Ort: Barchfeld
27.624 Beiträge
 
Delphi 12 Athens
 
#16

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 21. Nov 2013, 09:06
In der Doku?
Detlef
"Ich habe Angst vor dem Tag, an dem die Technologie unsere menschlichen Interaktionen übertrumpft. Die Welt wird eine Generation von Idioten bekommen." (Albert Einstein)
Dieser Tag ist längst gekommen
  Mit Zitat antworten Zitat
Benutzerbild von blondervolker
blondervolker

Registriert seit: 14. Sep 2010
Ort: Bei: Leeeiipzzhhh
381 Beiträge
 
Delphi XE2 Architect
 
#17

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 21. Nov 2013, 09:47
Oiiihhh,habe gepennt.
Naja mein Spruch unten drunter gilt leider auch für mich....
www.bewerbungsmaker.de
  Mit Zitat antworten Zitat
Benutzerbild von Back2Code
Back2Code

Registriert seit: 6. Feb 2012
Ort: Deutschland
272 Beiträge
 
Delphi XE7 Professional
 
#18

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 27. Nov 2013, 10:26
Gibt es hier im Forum noch Beispiele in Form von Pdf einer richtigen Software Dokumentation wo auf Funktionen / Parameter von Klassen / Methoden eingegangen wird?
00111100001100110010000001000100011001010110110001 1100000110100001101001
  Mit Zitat antworten Zitat
Graberius

Registriert seit: 22. Nov 2013
11 Beiträge
 
Delphi XE5 Architect
 
#19

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 9. Dez 2013, 12:53
Sichwort Dokumentation
Egal ob du jetzt Object Pascal, C/C++, Java, Groovy, Velocity, HTML oder JavaScript Programmierst...
Kommentier wenigstens was eine Methode oder Funktion machen soll!!!

Geändert von Graberius ( 9. Dez 2013 um 12:54 Uhr) Grund: Delphi ist die IDE und OP die Sprache xD
  Mit Zitat antworten Zitat
Benutzerbild von MaBuSE
MaBuSE

Registriert seit: 23. Sep 2002
Ort: Frankfurt am Main (in der Nähe)
1.840 Beiträge
 
Delphi 10 Seattle Enterprise
 
#20

AW: Was gehört alles in eine richtige Dokumentation?

  Alt 9. Dez 2013, 14:25
Gibt es hier im Forum noch Beispiele in Form von Pdf einer richtigen Software Dokumentation wo auf Funktionen / Parameter von Klassen / Methoden eingegangen wird?
Ja,

z.B.http://docs.embarcadero.com/products...hivclwin32.pdf
( Achtung: das PDF hat 25622 Seiten und ist ca. 400 MB Groß )

Das ist die Hilfe zur VCL von D2007 als PDF.
Diese wurde die die Online-Hilfe mit Doc-O-Matic erstellt.
(Habe ich schon weiter oben beschrieben)

Apropos Delphi Dokumentation / Hilfe:
Das hier ist eine ganz gute Übersicht
http://docs.embarcadero.com/products...udio/index.php
(°¿°) MaBuSE - proud to be a DP member
(°¿°) MaBuSE - proud to be a "Rüsselmops" ;-)
  Mit Zitat antworten Zitat
Antwort Antwort
Seite 2 von 4     12 34      


Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 06:11 Uhr.
Powered by vBulletin® Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz