Sonstiges > Offtopic

Dokumentationsvorlage LN Anwendungen

<< < (2/3) > >>

_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  8)

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. 

Navigation

[0] Themen-Index

[#] Nächste Seite

[*] Vorherige Sete