Dokumentationsvorlage LN Anwendungen

[_Arne_]

Moin Moin,

bin auf der Suche nach guten Doku-Vorlagen im Lotus Notes Umfeld,
die man einem Entwickler an die Hand geben kann.

Hat sowas zufällig jmnd. von euch rumliegen?

Gruß,
Arne 

[Marinero Atlántico]

Hi,

1. es gibt unterschiedliche Arten von Dokumentationen, je nach Adressat und Intention.
D.h. was willst du:
A Endanwenderdokumentation
B Dokumentation für Betrieb (Admin-Doku)
C Dokumentation für Entwickler, die Anwendung erweitern wollen.

Wunder Templates gibt es für keines.

Für A und B tendiere ich dazu, diese nach Rollen in der Anwendung und darunter nach konkreten Aufgaben zu gliedern.
Sowas wie ACL und die Navigatoren muss man natürlich global beschreiben.
Bei C ist es schon sehr hilfreich, wenn der Entwickler es einsieht, dass Kommentare in code Sinn machen.
Für Überblicksdarstellungen ist Visio ganz ok.
Es sollte darauf geachtet werden, dass beim Schreiben wirklich an die Zielgruppe gedacht wird.

Gruß Axel

 

[qojote]

Hi,

ich mach mir da auch grad Gedanken drüber hab aber leider auch noch nichts gefunden.
Wäre schön wenn du falls du was findest einfach mal postest.

Gruß
Qojote

[Marinero Atlántico]

Ohne jetzt eine Grundsatzdiskussion starten zu wollen, aber vernünftige Dokumentation ist imho eine komplexe, anwendungs-, organisations- und zielgruppenspezifische Aufgabe.
Es ist ein Kommunikationsmedium und somit inherent komplex und inherent unscharf (weil Menschen sich eben missverstehen). 

Für Systemdokumentation ist das folgende hilfreich:
In jedem Agenten, jeder Funktion und jede Subroutine im Kopf sowas zu schreiben wie:

Code

%rem
wann erstellt:
von wem erstellt::
von wem geändert (Liste):
Kurzbeschreibung:

Langbeschreibung:




ReM ausgeremt: Beteiligte Gestaltungselemente war Schwachsinn und das mache ich auch nicht.
%end rem

Das wäre dann so ähnlich wie JavaDocs. Wobei JavaDocs per automatische Codegenerierung durch das javadoc-Tool ein Bündel von Html-Seiten erstellt.
Das ist aber nicht die gesamte Dokumentation.

Daneben gibt es noch grobgranularere Überblicksdokumentationen, wo die Beziehungen zwischen den Code Elementen beschrieben werden (z.B. Beziehung von Agent zu Dokument-Typ). Graphische Methoden bieten sich hier an. Für Notes benutze ich dabei eine freizügige Benutzung von allen Software-Diagrammtypen, die mir in Visio gut gefallen. Das ganze fundiert mit gewissen UML-Kenntnissen und v.a. auch viel Freitext.
Auch in Java ist die Frage, ob man jetzt UML mehr als Skizzenformat oder als semantisch eindeutige Modellierungsformat benutzen soll, umstritten.

Automatisierende Tools sind sowieso grundsätzlich umstritten. Viele Leute befürworten die Anschaffung von Digitalen Kameras und möglichst großen Whiteboards.

Bei einem guten Softwareprozess gibt es im Projektverlauf einen Fluss, wo die Enddokumentation quasi aus den Planungsdokumenten zu Anfang abgeleitet sind und das funktioniert.

Ich hab schon einige Organisationen erlebt, die durch die teure Erstellung von "Dokumentationsrichtlinien" das ganze bürokratischer, verlogener und ineffizienter gemacht haben als es vorher war.

Ansonsten würde ich mir Teamstudio anschaffen und nur das zu dokumentieren, was nicht durch Teamstudio Analyzer abgedeckt ist.

Gruß Axel

[TMC]

Ich kann da Axel's Meinung und Erfahrung nur zustimmen.

Ich habe gerade überlegt, mal als Anhaltspunkt hier ein paar Hauptkapitelüberschriften für die Gliederung einer Admin-, Entwickler- und Anwenderdoku reinzuschreiben - aber ohne konkret zu wissen was dokumentiert werden soll (Art und Umfang der App, etc.) ist das schwierig bis unmöglich was allgemeines zu empfehlen.

Dazu kommt bei der Endanwenderdoku: Wer ist die Zielgruppe? Leute die schon jahrelang Notes anwenden oder soll die Doku auch für Neulinge taugen, muss man also z.B. auch erwähnen, wie eine Dokument von einer View heraus geöffnet werden kann?
Meine Erfahrung zeigt, dass die meisten Endanwender eh die Doku nie lesen werden. Besser daher: Mehr Zeit in die Schulung und dann in die Betreuung der ersten Wochen nach der Einführung stecken. Am besten ist es eh, wenn die App Notestypisch intuitiv aufgebaut ist und man nur auf Besonderheiten eingehen muss.

Matthias

[_Arne_]

Moin,

ihr habt natürlich recht, es handelt sich letztenendes um eine Kurzdoku über die "Knackpunkte" einer Anwendung.

Frei nach dem Motto " Welche Agents laufen wann /  welche Besonderheiten gibt es u.s.w."

Der Leser der Doku hat also die Datenbank + Designer (und kennt sich auch damit aus).
Es soll erreicht werden das bei Fehlern nicht erstmal der ganze Code durchsucht werden muss  um die Anwendung zu verstehen.

Gruß,
Arne 

[TMC]

Hi Arne,

dann würde ich das auch entsprechend im Word gliedern.

z.B.

1. Über die DB
allgemeines Gefasel.

2. Scheduled Agenten
2.1 Agent 1
    Details (wie geplant, was macht der, etc.)
2.2 Agent 2
    Details (wie geplant, was macht der, etc.)

3. ACL
3.1 Rolle [ A ]
     Details zur Rolle (was darf der, welche Verbergen-Wenn-Formeln sind betroffen, etc.)
3.2 Rolle [ B ]
     Details zur Rolle (was darf der, welche Verbergen-Wenn-Formeln sind betroffen, etc.)
3.3 ACL-Grundeinstellung für DB-Admins
     ACL-Screenshot mit Erklärung
3.4 ACL-Grundeinstellung für Editoren
     ACL-Screenshot mit Erklärung
3.5 ACL-Grundeinstellung für Leser
     ACL-Screenshot mit Erklärung
3.6 ACL-Grundeinstellung für ?
     ACL-Screenshot mit Erklärung

4. Aufbau der DB
Nun wird es wohl individuell. Da können z.B. Visio-Charts (wie oben von Axel erwähnt) sehr hilfreich sein.
Hier kannst Du z.B. auch über ein Flußdiagramm aufzeigen, wie ein Workflow läuft.
Auch auf Script-Libraries eingehen. Und natürlich Klassen falls es diese gibt.
Und natürlich auf sämtliche Fallstricke und Besonderheiten.

5. Dokumentation
Ich würde noch erwähnen, wo überall Anpassungen der DB dokumentiert werden müssen (z.B. [selbstverständlich] in der jeweiligen Routine, im "About This Database" - Dokument, in einer Projektdokumentation etc.

6. Standards, IDE, Zielgruppe
Welche Standards müssen eingehalten werden? (z.B. Option Declare, einheitliche Präfixe für Variablen, etc.)
Welche Notes-Version darf für's Entwickeln benutzt werden?
Welche Client-Versionen setzen die Anwender ein?
etc.


7. Rollout / Produktivsetzung
Wie sehen die Schritte aus, wenn man Änderungen in der DB vorgenommen hat und das ganze jetzt produktiv setzen will?
Evtl. auch Testszenarien, Keyuser, Freigabeverfahren etc.

8. .....
Was sonst noch wichtig genug ist, um einen Hauptpunkt daraus zu machen 

---------------

Viel mir jetzt spontan so ein, habe sicherlich noch einiges vergessen.

[Marinero Atlántico]

Das von Mathias ist mir eher schon ein bischen zu viel.
In der Kürze liegt die Würze.
Ich bin schon oft in die Situation gewesen, mich in eine Zusammenballung von einer Anwendung aus 5 bis 20 Notes Datenbanken Dinge zu reparieren.

Am wichtigsten ist, dass ihr dem Entwickler klar einschärfst,
- dass er Errorhandling verwenden MUSS (immer noch erstaunlich, wie viele Leute es nicht wissen, wie das geht).
@isError und On Error goto ist MUSS.

- Option Declare muss verwendet werden.
 
Dann eine Beschreibung der Funktionsweise jeder Datenbank (kurz).
Dann die Beziehungen zwischen den Datenbanken (wichtigste Punkte, wenn da mal ein Lookup gemacht wird ist das nicht so schlimm, solange mit @isError, natürlich). Auch Integration mit Fremdsystemen (über .csv ist ziemlich beliebt) muss erklärt werden.

Viel wichtiger sind imho (und ich spreche aus Erfahrung) die Kommentare im Code. Wirklich schwierige Patienten kommen durch das folgende Szenario zustande:
Step 1: Eine Datenbank wird von einem Dienstleister gekauft mit offenen Design.
Der Code ist aber nicht gut erklärt, weil die keinen Bock auf Kommentare hatten.

Step 2: Einem Projektmanager (am besten einer der Sorte, der ja schonmal eine Notes Datenbank programmiert hat, meist eine sehr simple) will mehr Kreativität in sein erlahmtes Meeting-Dasein bringen und fordert von einem unerfahrenen internen oder externen Entwickler ein im Grunde meist völlig unnötiges Feature.

Step 3: Der neue Entwickler wird (wir sind ja in der Wirtschaft) unter Zeitdruck gesetzt, versteht den code nicht und wurstelt da irgendwie effizient aber ohne ein nachhaltiges Konzept zu haben rum. 
 
Step 4: In den nächsten Monaten werden noch ein paar halbherzige Code-Fixes gemacht, aber irgendwann brechen Teile zusammen.

Komplexere Dinge wie SkriptLibraries und Klassen können alles übersichtlicher machen. Ich hab aber gerade im Domino Umfeld viele Fälle von Klassen gesehen, die mehr dazu dienten, dass der Entwickler seine ersten Schritte mit OO macht (was OK ist). Das kann dann leider sehr unübersichtlich werden. Wenn er da unsicher ist, soll er es nutzen aber viel kommentieren.

Auch wenn MS-Api Funktionen eingebunden werden, viel kommentieren.

Wenn man schon programmiert, dann soll man wenigstens wissen, dass der Kampf um guten, übersichtlichen Code nie vollständig gewonnen werden kann aber immer geführt werden muss.
Je besser die Leute sind, desto mehr scheinen sie das zu wissen. Auf der Ranch tummeln sich viele Leute, die wirklich große Projekte machen. Und gerade diese Leute wissen das.

Ein Patentrezept gibt es nicht.
Je weniger Doku desto besser, aber dort die wichtigsten Punkte aufführen und ausserdem ist der code die eigentliche Dokumentation (Kommentare).

Gruß Axel


P.S. Ein großer Vorteil von Java ist, dass mittlerweile viele Leute Design Patterns kennen + nutzen und das hilft schon eine Menge, um vor Überraschungen zu schützen.

[Marinero Atlántico]

Ich bin bekennender Visio User.
Was dort rauskommt, dient aber u.a. auch dazu, um Projektmanager etwas mit Bildern an die Hand zu geben.
Das eigentlich soziale an mir ist, dass ich Kommentare schreibe und nicht nur versuche etwas lauffähig zu machen, sondern etwas gut zu machen.
Diese Kommentare schreibe ich so, dass sie auch weniger bibliophile Leute als ich verstehen.

[Marinero Atlántico]

Nochmal: Es gibt nicht den einen, richtigen Masterplan, wie man Projekte dokumentiert.
Viele Dinge wie RUP und angeblich auch ander Software-Projekt-Pläne von Andersen Consulting und Konsorten sind sehr umfangreich. Jedoch erzeugt das eine Menge Arbeit.
Schliesslich muss auch jede Dokumentation synchron mit dem Code gehalten werden (Arbeit).
Die Agile Bewegung sagt nun, dass solche Templates erfahrene Leute eher behindern als es ihnen nützt.
Je "perfektionistischer" die Richtlinien sind, desto mehr sind die Leute mit der Einhaltung beschäftigt und denken vielleicht weniger an den Addressaten ihrer Dokumentation. 

[TMC]

Ich muss auch mal endlich dokumentieren.

Heute hatte ich ein Schreck-Erlebnis.

Ich hatte etwa vor 4 Monaten eine App geschrieben. Eigentlich ziemlich simple DB.
Allerdings sind diverse Setupdokumente - und viele Abhängigkeiten vorhanden.
Z.B. wenn in Setupdok 13 im Feld 7 das Flag auf "1" ist, dann wird in Setupdok7 nachgesehen, ob Werte aus Setupdok 3 oder aber aus Setupdok4 ausgelesen werden in einer Maske. Darauf aufbauend gibt es Hide-When-Formeln. Es gibt zig solcher Abhängigkeiten.

Jetzt musste ich da schnell mal was zusätzliches einbauen.

Das hat mich fast 1 Stunde Zeit gekostet, da ich erstmal die DB wieder "neu lernen" musste.
Die Änderung selbst war in 2-3 Minuten umgesetzt, es kam ein neues Feld hinzu.

Fazit: So was muss unbedingt dokumentiert werden. Mich hatte das nur 1 Stunde Zeit gekostet, weil ich die DB selbst entwickelt hatte. Ein "Fremder" bräuchte da sicherlich die doppelte Zeit (mindestens).

Die Dokumentation dieser erwähnten DB dauert schätzungsweise 1 Stunde, wenn man es gleich nach dem Entwickeln macht, ca. 2 Stunden wenn man (so wie ich jetzt) nach etwa 4 Monaten damit anfängt und schätzungsweise 4 Stunden, wenn man die DB gar nicht (mehr) kennt.

Diese Dokumentation steht nun.
Meine Änderung heute würde schätzungsweise ca. 5-10 Minuten Zeit beanspruchen (+ 2-3 Minuten Dokumentations-Updaten).
Mein Hauptfehler war nicht nur, keine allgemeine Dokumentation zu haben, sondern auch dass meine Formelsprache sehr unzureichend geREMt war.

[Axel]

Ich muss auch mal endlich dokumentieren.

Heute hatte ich ein Schreck-Erlebnis.

Ich hatte etwa vor 4 Monaten eine App geschrieben. Eigentlich ziemlich simple DB.
Allerdings sind diverse Setupdokumente - und viele Abhängigkeiten vorhanden.
Z.B. wenn in Setupdok 13 im Feld 7 das Flag auf "1" ist, dann wird in Setupdok7 nachgesehen, ob Werte aus Setupdok 3 oder aber aus Setupdok4 ausgelesen werden in einer Maske. Darauf aufbauend gibt es Hide-When-Formeln. Es gibt zig solcher Abhängigkeiten.

Jetzt musste ich da schnell mal was zusätzliches einbauen.

Das hat mich fast 1 Stunde Zeit gekostet, da ich erstmal die DB wieder "neu lernen" musste.
Die Änderung selbst war in 2-3 Minuten umgesetzt, es kam ein neues Feld hinzu.
...

Diese Erlebnisse kenn' ich und hass' ich. Allerdings hab ich den inneren Schweinehund noch nicht besiegen können. 
Aber ich muss mich jetzt unbedingt dranmachen, denn zumindest die Administration der DBs wird auch von einer Kollegin gemacht.

Ich hab aber bisher noch keine Idee gehabt wie man eine DBs einigermaßen sauber dokumentiert.

Ich bin bekennender Visio User.
Was dort rauskommt, dient aber u.a. auch dazu, um Projektmanager etwas mit Bildern an die Hand zu geben.
Das eigentlich soziale an mir ist, dass ich Kommentare schreibe und nicht nur versuche etwas lauffähig zu machen, sondern etwas gut zu machen.
Diese Kommentare schreibe ich so, dass sie auch weniger bibliophile Leute als ich verstehen.

Kannst du mal ein Beispiel hier anhängen. Ich hab auch Visio und auch mal angefangen damit, aber so ganz hat mich das Ergebnis nicht zufriedengestellt.


Axel

[Wipe]

Hallo,

hab mal von Gedys so ne offene DB gehabt in der man bis zur Feldebene dokumentieren konnte. Ist zwar ziemlich starr aufgebaut aber jederzeit brauchbar. Werd mal am Dienstag (Montag = Urlaub =  ) schauen wo ich das Teil habe.

Bubble

[koehlerbv]

Hm, mit dem Ding haben die wohl in frühen Zeiten selber dokumentiert. Ich wage aber zu bezweifeln, dass das Teil Freeware ist.

Bernhard

[Timo Schüring]

Hiho,

ich bin an diesem Thema auch sehr interessiert - muß nämlich noch bis Mitte Januar eine Hausarbeit in Projektmanagement schreiben und dachte mir ich mache etwas zum Thema Lotus Notes 

Da bei uns im Unternehmen so einige Lotus Notes Anwendungen in Gebrauch sind und das ganze historisch Gewachsen ist und immer mehr dazu kommt, wirken sich die fehlenden Dokus mehr mehr negativ aus.

Ich stell mir also vor, das ich als Hausarbeit eine Ausarbeitung mache, wie man Lotus Notes Anwendungen (Datenbanken) ordentlich im Laufe eines Projektes dokumentieren kann (sollte).

Wäre da für jeden Input dankbar