Eure favorisierte Form der Dokumentation

[Daniel]

Tach auch,

:stupid:

manch einer von Euch klickt ja nicht nur in der DP herum, sondern programmiert ja nebenbei auch noch. Unter Umständen sogar mit Kollegen.
Mich würde mal interessieren, was sich da bei Euch als effizienteste Form der Dokumentation herauskristallisiert hat. Sei es Dokumentation, die fokussiert ganz konkret einzelne Aspekte Eurer Projekte adressiert oder auch Dokumentation, die das "Große Ganze" beschreibt und die Zusammenhänge zwischen den diversen Bestandteilen bzw. Modulen.

Ich kenne Firmen, die erfolgreich mit Word und Excel arbeiten, andere legen sich ein Wiki an. Manche Dokumentationsprojekte funktionieren, andere driften vom Projekt ab und schaffen so eine vielleicht lustige, aber nutzlose Parallelwelt.
Was hat bei Euch gut funktioniert?


Vorrangig bin ich an Praxisberichten interessiert - weniger an Euren Vorstellungen, warum Methode X oder Y Eurer Ansicht nach nicht funktionieren kann.

[dummzeuch]

Ich habe Wikis bei zwei Jobs ausprobiert, aber ich bin anscheinend der einzige, der sie praktisch findet und/oder in der Lage ist, darin Artikel zu schreiben. Funktioniert hat eigentlich immer nur Word (oder OpenOffice), reine Textdateien und Uebersichtsbilder (mit yEd).

Eine etwas abwegige Art der Dokumentation sind fuer mich meine Blog-Posts. Solange keine Firmeninterna davon betroffen sind, finde ich es ganz gut, wenn ich mir selbst auf diese Art eine Gedaechtnisstuetze gebe und nebenbei vielleicht auch anderen helfe. Z.B. diese hier:

http://blog.dummzeuch.de/2015/04/27/...-tar-archives/

http://blog.dummzeuch.de/2015/04/09/...ndows-service/

[Lemmy]

wir verwenden gerade auch ein Wiki, wobei ich dummzeuchs bestätigen kann: Es gibt nur sehr wenige die Input liefern, noch weniger die sich im Wiki informieren. Wenn aber inzwischen Fragen bei mir landen kann ich die oft über einen entsprechenden Link ins Wiki einfach beantworten - deshalb werde ich auf dem Weg erst mal weiter machen.

Office Dateien bin ich ganz schnell wieder weg gekommen, da in kürzester Zeit unterschiedliche Versionen im Umlauf waren...

[vagtler]

Wir verwenden sowohl für unsere internen Produkte als auch für alle externen Projekte ein Enterprise-Wiki mit integrierten Google Docs zur Dokumentation. Das hat sich für uns als effizienteste Art der Kollaboration erwiesen.

[Bernhard Geyer]

Ich denke es kommt immer auf die Art der Dokumentation an.

Benutzerhandbücher, Pflichtenheft, ...: Word-Dokument das als PDF zum Kunden gesendet wird.
Interne Dokumentation die auch mal "Formlos" erfolgt: Wiki. Dazu haben wir mittlerweile Confluence (https://www.atlassian.com/software/confluence)
Dan natürlich für Problemfälle/Fehler/Anforderungen/User Strories/ gibts Jira.

Punkt 2 und 3 lassen sich schön miteinander Verknüpfen und können auch direkt mit dem Kunden zusammen mit "Leben" gefüllt werden.
Gegenüber früher werden weniger Excellisten/Word-Dokumente oder Mails ausgetauscht.

[BUG]

Ich sehe gerade den Ablauf in einem akademischen Projekt, wobei mir die internen Releases mit dazugehörigen Architekturdokumenten gefallen. So ein Dokument zwingt einen im Großen ab und zu ein konsistentes Bild zusammenzutragen und lesbar auszuformulieren. Ist natürlich aufwendig.

[TBx]

Für die Nachvollziehbarkeit es Codes gilt: The code is the documentation. Verstehe ich den nach einiger Zeit nicht mehr, habe ich falsche Bezeichner gewählt und korrigiere das.
Für die Hintergründe des Projektes oder auch Erķlärungen, warum welcher Weg eingeschlagen wurde, gibt es reine Textdateien, PDFs, jpgs --> auf jeden Fall nur Formate, für die es eine Vielfalt von Readern gibt.
Das fliegt dann in ein Dokumentationsverzeichnis, welches mit allem anderen im GIT landet. Für die Historie ist das GIT da, lange Unit.- oder Funktionsheader, in denen jeder Sch*** dokumentiert ist, sind mir ein Greul.
Ich scheue auch nicht davor zurück, in Kommentaren nur auf Dokumente im Dokumentationsverzeichnis zu verweisen.

[Phoenix]

Wikis haben Erfahrungsgemäß das Problem, dass sie schnell veralten. Kaum jemand denkt im Regelfall daran, wenn er etwas im Code ändert, das auch im Wiki nachzupflegen. Wir haben bei mir auf der Arbeit das gleiche Problem. Das lässt sich mit etwas Konsequenz und Checklisten (Punkt: Doku aktualisiert? Beim Ticket / Task der abzuarbeiten ist) zwar etwas eindämmen, aber nicht ganz vermeiden.

Ich persönlich bin ein Fan von guter Code-Dokumentation, bei der man auch konzeptionelle Doku zu Architektur und abläufen in der Solution als Einzelfiles mit eincheckt und dort mit pflegt. Die aktualisierte Doku ist damit nur einen weiteren Commit entfernt, und man hat alles beisammen. Aus der Doku (Kommentare im Code sowie Konzeptionelle Doku) wird beim Release dann auch gleich die technische Doku als Webseite mit gebaut, über die der gesamte Inhalt inkl. Architekturdiagrammen etc. abrufbar ist. Wir benutzen dafür DocumentX von Innovasys. Wir sind aber ja auch eine .NET Schmiede, und ich weiss nicht ob das auch mit Delphi tut.

Grundsätzlich halte ich den Ansatz, die Doku zusammen mit dem Quellcode zusammen zu versionieren, und alles in einem Checkout zu haben, aber für das beste. Bei mir vor allem deswegen, weil wir das Dokumentationstool eben auch gleich als Plug-in in der IDE haben, und wir bei der Dokumentation daher niemals einen Medienbruch haben. Dieses Unkompliziertheit, alles gleich bei der Hand zu haben, sorgt dafür das die Doku auch deutlichst besser gepflegt wird als in einer separaten Ablage (wie z.B. ein Wiki).

[Dejan Vu]

Wir dokumentieren mit Confluence. Dabei werden Architekturansätze, Codepatterns und sonstige Systemdokumentation festgehalten und gepflegt. Code ist clean, d.h. enthält die notwendigen Dokumentationen der API und wird durch Review so gehalten, das er verständlich ist.

Über Resharper sehen wir, wann sich (zumindest bei den Parametern) die ///-Doku zu sehr von der Methode unterscheidet.

Klappt. Weil wir einen Softwarearchitekten haben, dessen Hobbies u.a. Peitschen, Teeren und Federn ist.

[Luckie]

Das funktioniert nicht. Also eine externe Dokumentation. Da könne mir die Theoretiker noch so viel erzählen. Wer sucht im Wiki schon nach Antworten, wenn er den Quellcode vor sich im Editor offen hat? Und eine externe Doku hängt dem aktuellen Stand immer hinterher. Und ich habe noch keinen Kollegen getroffen, der die externe Doku pflegt. Besser aussagekräftiger Code mit sparsamen Kommentaren warum so und nicht anders.

[redox]

Zitat:

Zitat von Luckie (Beitrag 1308424)

Das funktioniert nicht. Also eine externe Dokumentation. Da könne mir die Theoretiker noch so viel erzählen. Wer sucht im Wiki schon nach Antworten, wenn er den Quellcode vor sich im Editor offen hat? Und eine externe Doku hängt dem aktuellen Stand immer hinterher. Und ich habe noch keinen Kollegen getroffen, der die externe Doku pflegt. Besser aussagekräftiger Code mit sparsamen Kommentaren warum so und nicht anders.

Jupp.

Benutzerhilfe mit http://www.helpndoc.com/de

Ansonsten RTF-Dateien (ohne Bilder, die mit WordPad angezeigt werden können) oder PDFs mit LibreOffice.


Eventuell problematische Quelltextzeilen kommmentiere ich immer mit
...// Depp
// Depp weil es mit i < 0 abschmiert, daher i := abs(i)

https://de.wikipedia.org/wiki/Depp

:wink::oops::-D

[Uwe Raabe]

Zitat:

Zitat von redox (Beitrag 1308428)

Eventuell problematische Quelltextzeilen kommmentiere ich immer mit
...// Depp

DEPP = Delphi Extreme Problematic Programming

[hathor]

DEPPEN = Delphi Extreme Problematic Programming errors and nonsense

[Bernhard Geyer]

Zitat:

Zitat von Phoenix (Beitrag 1308415)

Wikis haben Erfahrungsgemäß das Problem, dass sie schnell veralten. Kaum jemand denkt im Regelfall daran, wenn er etwas im Code ändert, das auch im Wiki nachzupflegen.

Wenn Sinnvollerweise im Quellcode (Stichwort JavaDoc und Co. ) kommentiert wreden kann, wird in 2015 (fast) keiner mehr das in einem (immer veralteten) extra Dokument machen.

Zitat:

Zitat von Phoenix (Beitrag 1308415)

Ich persönlich bin ein Fan von guter Code-Dokumentation, bei der man auch konzeptionelle Doku zu Architektur und abläufen in der Solution als Einzelfiles mit eincheckt und dort mit pflegt.

Hier wirds dann aber schwieriger wenn man z.B. ein Solution als Library für andere Anwendung hat. Dann muss man bei den anderen Anwendungen welche diese Library verwenden wo dort wieder die Doku liegt. Und Hyperlinks zwischen der Dokumentation der Anwendungen und der Library sind auch schwer möglich.

Zitat:

Zitat von Phoenix (Beitrag 1308415)

Wir sind aber ja auch eine .NET Schmiede, und ich weiss nicht ob das auch mit Delphi tut.

Lösungen gibts auch für Delpi. Evtl. nicht so umfangreich.

[mm1256]

Hallo,

externe Doku mit Word hat sich nicht bewährt. Zu umständlich, schwer zu pflegen, und wenn man was sucht oder braucht war es oft nicht aktuell. Die wichtigsten (programmier-)technischen Hinweise stehen darum im Quelltext. Für globale Zusammenhänge bei mehreren Modulen und die interne Dokumentation gibt es ein kleines Selbstgestricktes (DB, ein paar indizierte Felder zum schnellen Auffinden und ein Memo mit der Doku, sowie ein DateTimeFeld und ein User-Feld welche bei einer Änderung automatisch gesetzt werden. Dann weiß man immer automatisch, wer war's) und ansonsten gilt die Devise: Die Hilfe ist die beste Dokumentation. Darum ist bei Abschluss eines dokumentationswürdigen Vorganges sofort der Eintrag im Hilfesystem (Help&Manual) vorzunehmen, denn es müssen ja, damit die kontextsensitive Hilfe funktioniert, im OI auch die Werte des HelpContext gesetzt werden.

[Mavarik]

Alle Änderung bleiben im Quellcode...

Beispiel:

Delphi-Quellcode:

// For i:=0 to Liste.Count do 
   For k:=1 to Liste.Count-1 do // FL 10.07.15

Delphi-Quellcode:

for k:=0 {1 // AB 11.07.15} to Liste.Count-1 // 0 war doch richtig...

oder

Delphi-Quellcode:

for k:=0 {1 // AB 11.07.15} to High(Liste) // 0 war doch richtig... // FL 12.07.15 besser mit High

Irgendwann habe ich angefangen auf Documentation Inside um zu stellen... Aber schwupti war es in der nächsten Delphi Version nicht mehr dabei...

[Dejan Vu]

Zitat:

Zitat von Luckie (Beitrag 1308424)

Das funktioniert nicht. Also eine externe Dokumentation.

Die Architektur ändert sich sehr selten. Und wenn, wird die Doku nachgezogen. Das funktioniert, aber es braucht einen, der hinterher ist und dafür sorgt, das die Doku nachgezogen wird.
@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht.

[bernau]

Zitat:

Zitat von Mavarik (Beitrag 1308451)

Alle Änderung bleiben im Quellcode...

Bei mir auch.

Zitat:

Zitat von Dejan Vu (Beitrag 1308452)

@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht.

Änderungen im Quellcode sollen sofort in's Auge springen. Bei einem VCS (welches ich mittlerweile verwende ;-) ) müsste man erst aktiv die alte Version vergleichen.

Sollte die Kommentare allerdings den Code unleserlich machen, werden diese Kommentare entfernt, oder ich belege die Kommentare auch einem Verfallsdatum. Heist, die Kommentare werden ab dem Datum entfernt bzw. es bleibt dann nur noch ein Kommentareinzeiler mit dem Änderungsdatum, damit ich ich darauf aufmerksam gemacht werde. Dann kann ich in's VCS hinein schauen.

[Dejan Vu]

Zitat:

Zitat von bernau (Beitrag 1308463)

Änderungen im Quellcode sollen sofort in's Auge springen.

Nur frage ich mich, was das für einen Mehrwert hat. :gruebel: Mich interessiert es nicht, was dort *vorher* stand. Das, was jetzt dort steht, ist relevant. Na ja. OT.

[Bernhard Geyer]

Zitat:

Zitat von Dejan Vu (Beitrag 1308491)

Zitat:

Zitat von bernau (Beitrag 1308463)

Änderungen im Quellcode sollen sofort in's Auge springen.

Nur frage ich mich, was das für einen Mehrwert hat. :gruebel: Mich interessiert es nicht, was dort *vorher* stand. Das, was jetzt dort steht, ist relevant. Na ja. OT.

Die Geschichte einer Quellcodezeile ist auch eine art von Dokumentation. Übers CVS ist sie halt teilweise relativ umständlich/zeitverzögert abzufragen.

[Valle]

Wir verwenden Python, daher bin ich hier vielleicht etwas außenvor.

Python unterstützt Dokumentation als Teil der Sprache. Packages, Klassen und Methoden können jeweils mit einem String beginnen, der die Dokumentation beinhaltet. Es existieren entsprechende Tools um das dann in beliebige andere Dateiformate umzuwandeln. Bei uns klappt das eigentlich ganz gut.

Hier mal ein Beispiel, für die, die sowas noch nicht gesehen haben:

Code:

"""
My Module

>>> inline_code_example()
"""
 
class Foo:
    """
    My Class
    """
 
    def __init__(self):
        """
        My Constructor
        """
        pass
 
    def add(self, a, b):
        """
        Returns ``a`` + ``b``
        """
        return a + b

[bernau]

Zur Dokumentation des Quellcodes habe ich ja schon etwas geschrieben.

Dokumentation ist aber ein weit gefächtertes Thema. Zur Dokumentation gehört auch Pflichtenheft, Bedienungsanleitung, etc.

Mit Word-Dateien konnte ich nie wirklich etwas anfangen. Zumal die Arbeit immer an einer Person hängen bleibt.

Wir sind bei diesen Bereichen nun auf ein WIKI umgeschwengt. Zwar bleibt die Doku weiterhin die Aufgabe von 1-2 Personen. Aber Korrekturen (z.B. für die Rechtschreibung und Formulierung) können auf viele Personen aufgeteilt werden. Die Verwaltung des Dokumentes ist zentral. Es gibt keine verschiedenen Versionen. Bei Fragen kann man direkt auf den entsprechenden Link verweisen. Änderungen in der Doku sind leicht auffindbar.

Gute Erfahrung habe ich mit DokuWiki gemacht.

[p80286]

[/OT]
Dokumentation?

Die Form ist mir inzwischen ....egal. Aber stimmen muß sie. Oft genug steht da drin, was man gerne hätte, aber nicht was man programmiert hat.
(Sonst gäb es z.B. keine abweichenden Feldnamen:stupid:)

Gruß
K-H

[/OT]

[Mavarik]

Zitat:

Zitat von Dejan Vu (Beitrag 1308452)

@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht.

Doch habe ich...

Zitat:

Zitat von Dejan Vu (Beitrag 1308491)

Nur frage ich mich, was das für einen Mehrwert hat. :gruebel: Mich interessiert es nicht, was dort *vorher* stand. Das, was jetzt dort steht, ist relevant. Na ja. OT.

Ich kann nicht bei jeder Änderung es in der History nachschauen ob oder was sich da mal geändert hat...

Und ganz besonders, wenn etwas nicht funktioniert, möchte ich die versuche in Quelltext haben, damit ich nicht nach 2 Jahres nochmal das gleiche versuche was vorher schon nicht funktioniert hat.

Ganz besonders wichtig ist das wenn der Source an dieser Stelle auf den 1. Blick falsch erscheint... Dann ist ganz wichtig zu sehen warum? usw...

[mikhal]

Ist schon interessant, dass niemand Delphi Doc oder PasDoc genannt hat. Ich weiß, dass diese Projekte irgendwie alt sind und wohl nicht mehr wirklich weiterentwickelt werden, aber ich habe zumindest Delphi Doc in der Vergangenheit eingesetzt und war vom Ergebnis zufrieden.

Grüße
Mikhal

[TheMiller]

Zitat:

Zitat von mikhal (Beitrag 1308550)

Ist schon interessant, dass niemand Delphi Doc oder PasDoc genannt hat. Ich weiß, dass diese Projekte irgendwie alt sind und wohl nicht mehr wirklich weiterentwickelt werden, aber ich habe zumindest Delphi Doc in der Vergangenheit eingesetzt und war vom Ergebnis zufrieden.

Grüße
Mikhal

Ich wollte es auch gerade schreiben. Gerade in Zusammenhang mit Doxygen war ich immer sehr zufrieden. Es werden sowohl Web-Quelltexte, also auch "Hochsprachen" dokumentiert, als HTML-/PDF ausgegeben und mit Links interaktiv versehen!

[Dejan Vu]

Zitat:

Zitat von Mavarik (Beitrag 1308542)

Ich kann nicht bei jeder Änderung es in der History nachschauen ob oder was sich da mal geändert hat...

Und ganz besonders, wenn etwas nicht funktioniert, möchte ich die versuche in Quelltext haben, damit ich nicht nach 2 Jahres nochmal das gleiche versuche was vorher schon nicht funktioniert hat.

Ah.. Wir haben Unittests, da stellst sich die Frage nicht, ob irgendwer schon einmal etwas versucht hat. Weil, es funzt jetzt ja ;-)

Aber als ich selbst eine One-Man-Show war (ich unterstelle Dir das einfach mal), da wäre mir das auch ganz recht gewesen, zu wissen, was ich vorher schon einmal probiert habe.

[bernau]

Zitat:

Zitat von Dejan Vu (Beitrag 1308610)

Ah.. Wir haben Unittests, da stellst sich die Frage nicht, ob irgendwer schon einmal etwas versucht hat. Weil, es funzt jetzt ja ;-)

Du kannst also alle Programmbereiche mit Unittest kontrollieren und testen? Respekt.

Zitat:

Zitat von Dejan Vu (Beitrag 1308610)

Aber als ich selbst eine One-Man-Show war (ich unterstelle Dir das einfach mal), da wäre mir das auch ganz recht gewesen, zu wissen, was ich vorher schon einmal probiert habe.

Der Zusammenhang mit der One-Man-Show erschliesst sich mir nicht so ganz. Wenn ich alleine am Projekt arbeite, ist es gut zu wissen, was ich vorher schon mal programmiert habe. Wenn ich mit mehreren an einem Projekt arbeitet, dann muss ich das nicht mehr wissen. Aha? So, so! Sehr aussergewöhnliche Logik.

[Mavarik]

Zitat:

Zitat von Dejan Vu (Beitrag 1308610)

Aber als ich selbst eine One-Man-Show war (ich unterstelle Dir das einfach mal)

Da liegst Du falsch... Abgesehen davon möchte ich sehen wie Du einen Canvas 2 PDF Druck mit transparenter Overlay-Grafik in einen Unittest abkasperst...

90% Der Fehler die nach 30 Jahren in einer Software immer noch drin sind... Kannst Du mit Unittests überhaupt nicht erfassen

[Dejan Vu]

Zitat:

Zitat von Mavarik (Beitrag 1308679)

Abgesehen davon möchte ich sehen wie Du einen Canvas 2 PDF Druck mit transparenter Overlay-Grafik in einen Unittest abkasperst...

Wenn Du das wirklich sehen willst: Mein Tagessatz außerhalb Berlins beträgt 850 Euro zuzüglich Spesen... :mrgreen:

Du hast 30 Jahre alte SW und wir haben von Anfang an mit UT gearbeitet und können daher auch transparentes Hinterwutzrendering mit zwiegenopptem Tretoverlay an Shayderman-Splines kontradisoziieren (und zwar die mit der 3.Ableitung), ohne mit der Wimper zu zucken. Und zwar freihändig. Mit 100% Code Coverage. Mach DAS mal nach. ;-)

Mann. Canvas nach PDF. Transparente Overlaytechnik. Pah! Sowas machen wir als als Kata vor dem Daily Scrum. Vor! dem Frühstück. Als Einstieg. Für unsere Vertretungsassistenz.

So. :-D

Übrigens: Man kann so ziemlich alles testen. Kommt nur aufs Mocking Framework an. Aber bei Delphi sind einem da wirklich die Hände gebunden.

Aber zurück zum Thema. Einverstanden?

[pertzschc]

Zitat:

Zitat von Dejan Vu (Beitrag 1308681)

Pah! Sowas machen wir als als Kata vor dem Daily Scrum. Vor! dem Frühstück.

Vielleicht kannst Du Dich dann aufraffen, einmal vor dem Frühstück etwas im Bereich Hands-On oder Bestpractise zum Thema "Gute Unittests mit/für Delphi Applikationen" hier im Forum vorstellen.

Danke,
Christoph