![]() |
Eure favorisierte Form der Dokumentation
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. |
AW: Eure favorisierte Form der Dokumentation
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: ![]() ![]() |
AW: Eure favorisierte Form der Dokumentation
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... |
AW: Eure favorisierte Form der Dokumentation
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.
|
AW: Eure favorisierte Form der Dokumentation
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 ( ![]() 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. |
AW: Eure favorisierte Form der Dokumentation
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.
|
AW: Eure favorisierte Form der Dokumentation
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. |
AW: Eure favorisierte Form der Dokumentation
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). |
AW: Eure favorisierte Form der Dokumentation
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. |
AW: Eure favorisierte Form der Dokumentation
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.
|
AW: Eure favorisierte Form der Dokumentation
Zitat:
Benutzerhilfe mit ![]() 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) ![]() :wink::oops::-D |
AW: Eure favorisierte Form der Dokumentation
Zitat:
|
AW: Eure favorisierte Form der Dokumentation
DEPPEN = Delphi Extreme Problematic Programming errors and nonsense
|
AW: Eure favorisierte Form der Dokumentation
Zitat:
Zitat:
Zitat:
|
AW: Eure favorisierte Form der Dokumentation
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. |
AW: Eure favorisierte Form der Dokumentation
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:
oder
for k:=0 {1 // AB 11.07.15} to Liste.Count-1 // 0 war doch richtig...
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... |
AW: Eure favorisierte Form der Dokumentation
Zitat:
@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht. |
AW: Eure favorisierte Form der Dokumentation
Zitat:
Zitat:
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. |
AW: Eure favorisierte Form der Dokumentation
Zitat:
|
AW: Eure favorisierte Form der Dokumentation
Zitat:
|
AW: Eure favorisierte Form der Dokumentation
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 |
AW: Eure favorisierte Form der Dokumentation
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 ![]() |
AW: Eure favorisierte Form der Dokumentation
[/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] |
AW: Eure favorisierte Form der Dokumentation
Zitat:
Zitat:
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... |
AW: Eure favorisierte Form der Dokumentation
Ist schon interessant, dass niemand
![]() ![]() Grüße Mikhal |
AW: Eure favorisierte Form der Dokumentation
Zitat:
|
AW: Eure favorisierte Form der Dokumentation
Zitat:
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. |
AW: Eure favorisierte Form der Dokumentation
Zitat:
Zitat:
|
AW: Eure favorisierte Form der Dokumentation
Zitat:
90% Der Fehler die nach 30 Jahren in einer Software immer noch drin sind... Kannst Du mit Unittests überhaupt nicht erfassen |
AW: Eure favorisierte Form der Dokumentation
Zitat:
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? |
AW: Eure favorisierte Form der Dokumentation
Zitat:
Danke, Christoph |
Alle Zeitangaben in WEZ +1. Es ist jetzt 00:22 Uhr. |
Powered by vBulletin® Copyright ©2000 - 2025, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz