Dokumentation

[MartinHan]

Wie dokumentiere ich eine Anwendung, die ein Access-Front-End und eine MS-DB Backend hat?
Ziel der Doku ist, diese Anwendung an jemanden zu übergeben...weil ich alt werde...
Man kann das natürlich ganz einfach machen und ein Worddokument erstellen, wo alle Geschäftsvorfälle und deren Daten beschrieben sind.
Das war mir aber zu flach...
Ich habe mich in meiner beruflichen Vergangenheit mit Metadaten-Repositories beschäftigt, denn das ist hier das Mittel der Wahl.
Kommerzielle Produkte gibt es zwar, nur die sind relativ teuer.
Ich habe dann chatgpt gefragt, ob sie (er..es) eine Lösung hätte und sie kam mit einem Konstrukt um die Ecke, was mir gefallen hat.
Es sind ca. 15 Tabellen, die eine Anwendung nach dem Quadranten Modell (oben links: fachliche Funktionen, oben rechts fachliche Datenstrukturen, unten links Formulare und Funktionen, unten rechts Datenstrukturen) gut beschreibt.
Die IBM hatte mal so ein Repository, das bestand aus 850 DB2-Tabellen...wurde aber eingestampft.
Ich bin jetzt dabei, die Dialoge für eine Access-Anwendung zu schreiben, um die diese z.T.sehr detaillierte Dokumentation zu erstellen.
Ziel ist, jedes Object der Anwendung in seinem Umfeld sehen bzw. abfragen zu können:
Also welches Feld wird wo benutzt, welche Bedeutung hat es...welche Tabelle wird wo wie benutzt...welche Function oder Stored Procedure greift worauf zu und macht was?
Umfangreiche Abfragen und Analysen sind möglich.
Der Aufwand das zu erstellen ist allerdings hoch.
Hat jemand andere Erfahrungen gemacht?

Martin

[Bitsqueezer]

Hallo Martin,

meistens sind zu detaillierte Dokus etwas, was am Ende niemand benutzt, und was in 2 Wochen schon wieder seine Gültigkeit verloren hat, weil wieder einiges geändert wurde.

Ich würde daher keine starren Dokumente anlegen, außer einer generellen Funktionsbeschreibung vielleicht.

Für einen Nachfolge-Entwickler ist es definitiv zielführender, die Objekte da zu beschreiben, wo man die Doku wirklich braucht. In Access bei jedem Feld einer Tabelle, das nicht offensichtlich ist (wie etwa eine PK-AutoID), eine Beschreibung hinzufügen, wozu das Feld dient, wo man eine Lookup-Tabelle dazu findet (wenn es nicht bereits durch eine Referenz darauf offensichtlich ist, aber viele DB-Designer bauen auch referenzlose Datenbanken...), welche Werte darin was bedeuten (z.B. Statuscodes etc.).

Jede Tabelle sollte außerdem eine Tabellenbeschreibung bekommen.
Beides ist natürlich auch bei SQL Server möglich (und sinnvoll) über die Extended Properties. Es gibt auch Freeware-Tools, um diese zu verwalten und zu editieren, macht auf jeden Fall Sinn, weil SSMS hier etwas umständlich ist.

SPs/Views/UDFs sollten natürlich mit Kopf-Kommentaren ausgerüstet sein, Autor, Datum, kurze Änderungshistorie, Beschreibung der Funktion und (außer bei Views) der Parameter.

Das sind die Dokus, die wirklich zählen und die für gewöhnlich dann auch immer aktuell sind. Und die einem Entwickler wirklich helfen.

Was die SPs, UDFs, Views angeht: Ja, mit Redgate findet man z.B. sehr gute Doku-Tools, aber eben halt teuer.
Ich habe mir selbst eins gebaut, findest Du auf meiner Downloadseite unter "Database Documentation V1.2". Das ist eine kleine Access-Datenbank, benötigt nur ein paar wenige Objekte auf dem SQL Server, deren Code enthalten ist in einer Access-Tabelle.
Wenn Du das installiert hast, kannst Du einen Connectionstring zum SQL Server in einer anderen Tabelle speichern, dann mit dem SQL Server verbinden und dann alle oder nur die gewünschten Objekte laden. Das lädt keine Kommentare oder SQL-Code, nur die Namen und ihr Typ sowie die Abhängigkeiten der Objekte voneinander.

Am Ende kann man damit eine Excel-Datei ausgeben, die man im kostenlosen Editor yEd importieren kann. Der kann daraus ein Diagramm erstellen, bei dem man dann genau sehen kann, welche Objekte von was abhängen. Sehr praktisch: Das Fenster "Structure View": Listet jedes Objekt im Diagramm, wenn man dann draufklickt, zeigt er nur den Diagrammteil an, der zu dem betreffenden Objekt gehört, also alles, was direkt damit verbunden ist. So kann man ruhig alle Objekte in ein Diagramm importieren (und ein riesiges chaotisches Diagramm erhalten), und mit der Structure View genau das herausgreifen, was einen interessiert. So sieht man dann schnell die SP, die eine View verwendet, die eine View verwendet, die eine UDF verwendet und welche Tabellen involviert sind usw.
Perfekt für eine stets aktuelle Doku, weil man bei Bedarf eben einfach nochmal alle aktuellen Objekte importiert.

Für Access und VBA gilt natürlich vor allem bei VBA das übliche: Prozedur- und Codekommentare, wo immer nötig. Hier hilft vor allem MZTools, sowohl schnell Kommentarblöcke in Standardformat einzufügen und vorauszufüllen, als auch aus diesen eine komplette Dokumentation zu generieren. MZTools ist eh unverzichtbar und der Preis ist wohl auch unschlagbar.

Gruß

Christian