Sonstiges > Offtopic

Dokumentationsvorlage LN Anwendungen

(1/3) > >>

_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

--- Ende Code ---
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

Navigation

[0] Themen-Index

[#] Nächste Seite