Dokumentation von Notes-Feldern / XML

[cgorni]

Hi,

ich wollte eure Meinung hören, wie diese Idee von mir einzuschätzen ist. Leider hat bei OpenNTF und Notes.Net keiner eine Meinung dazu. Kein Feedback weit und breit.

Grob gesagt kann man mit der Idee Kommentare, die man in Notes-Feldern schreibt als eine Zusammenfassung  (quasi als Dokumentation) in HTML ausgeben lassen. Eine Variante macht etwas ähnliches mit Ansichten.

Das ganze ist mit XML/XSLT gemacht (mit diesem kleinen Projekt habe ich mir die Themen beigebracht).

Das Ziel von mir war, eine Art automatische Dokumentation aller (! :-) ) Design Elemente auf Knopfdruck herzustellen (mehrere HTML-Seiten, die automatisch erzeugt werden und von einer automatisch erzeugten Homepage zusammengehalten werden). Natürlich immer mit den Kommentaren, die man bei der Programmierung angibt.

Die Benutzung ist relativ einfach:
- im XSLT-code zwei Pfade an die eigenen Notes-Verzeichnisse anpassen
- die Dateien in das Verzeichnis <NotesDataDirectory>\xsl hineinkopieren
- im Notes Designer unter "Tools - DXL Utilities - Transformer ..." benutzen

Hier ist die zentrale Seite für das Beispiel auf openntf.org (mit Erklärung etc.)

Eine weiterführende Idee, die ich ganz interessant für dieses Projekt fände: Zusammenhänge zwischen Feldern dokumentieren. Entweder werden automatisch (sehr schwer) oder per REM Verbindungen zwischen Feldern dokumentiert und sind dann als Link mit in der Übersicht enthalten (ähnlich Funktion in Excel)

Es würde mich sehr freuen, wenn ich ein Feedback bekäme. Davon hängt es ab, ob ich den Weg weiter beschreite (=Idee ist doch nicht so doof) oder mir ein anderes Lern-Projekt im Bereich XML/XSLT ausdenke.


Gruß,
Christian

[koehlerbv]

Hut ab soweit, Christian !
Aber ich würde für soetwas wie gewohnt den Teamstudio Analyzer benutzen, der in seinen Möglichkeiten doch noch extrem viel weiter reicht.
Aber als Fingerübung ist die Idee sicherlich bestens geeignet.

Bernhard

[Marinero Atlántico]

Ich werde es mir jedenfalls mal anschauen.
Ein paar offene Punkte aus meiner Sicht (muss nicht richtig sein):
-  Es ist gut xml/xslt zu lernen, gerade im Hinblick auf Workplace.
- Anwendung ist die einzige Möglichkeit etwas zu lernen (du hast es getan).
- Es ist ziemlich schwierig ein Dokumentationssystem für Notes zu schreiben, dass wirklich Leuten aus der Praxis etwas bringt.
- Teamstudio ist teilweise recht gut als kommerzielles Projekt. Liefert die Design-Synopse nicht ähnliches?
- Für Entwickler etwas zu schreiben, ist wohl am schwierigsten.
- Ich bin ja genau die Zielgruppe. Ich hab in den letzten 5 Jahren viel über unzureichende Dokumentation rumgemault.
D.h. in den letzten 3 Jahren hat sich meine Sicht auch wieder ziemlich geändert.
Helfen grooooooßßßßeeee Blätter mit vielen Informationen dabei, Probleme in einer realen und komplexeren Anwendung. Ich denke absolut nein. Übersichtlichkeit kommt in eine Anwendung nicht durch Dokumentation sondern durch eine gute Architektur und ein gutes Design. Und für beides wurde Notes einfach nicht konzipiert.
So etwas begegnet mir in Albträumen: Ich soll Probleme in einer Notes Datenbank lösen und der interne Projektverantwortliche knallt mir freudestrahlend 200 Seiten auf den Tisch.
"So. Das dürfte ja jetzt kein Problem sein. Schliesslich haben wir uns die Mühe gemacht, mit diesem dollen Tool zu dokumentieren. Jetzt sind sie dran."
Wirklich schwere Fälle lassen sich aber damit ganz bestimmt nicht lösen. Das ist dann in der Anwendung selbst verwurstet. Notes ist als System prädistiniert für "rippling effects" (spelling?).
D.h. man ändert an einer Seite was und an anderer Stelle bricht das Chaos aus. 
Meiner Ansicht nach v.a. Weil es keine architektonische Trennung zwischen UserInterface-Code, Logik der Anwendung und Ablegen_in_dauerhaften_Speicher-Logik gibt.
Oder das Daten nicht in kleinen übersichtlichen Objekten zusammengefasst sind, sondern in Dokumenten mit viiiiieeeeellllleeeeennnnn Feldern.

Axel     

[cgorni]

Hi,

@koehlerbv
> Aber ich würde für soetwas wie gewohnt den Teamstudio Analyzer benutzen
Sehr schmeichelhaft der Vergleich  Ich kenne den Teamstudio Analyzer jetzt im Detail nicht, ich habe mich eher an einer Dokumentation ala javadoc orientiert, d.h.:

- Kommentare werden an verschiedenen Stellen der Notes Datenbank eingefügt
- Die Kommentare müssen einem bestimmten Format entsprechen
- Auf Knopfdruck wird eine Dokumentation ausgespuckt (momentan HTML)

Es geht mir also weniger um die einzelnen Designelemente, sondern darum mich dazu zu zwingen Felder (und andere 'Einzelteile' in Notes) zu kommentieren und daraus auch einen Nutzen (!) zu ziehen.

Insbesondere möchte ich nicht alles in der Dokumentation stehen haben wie in der Design Synopsis..

Der derzeitige Stand macht eigentlich schon genau das was ich mir vorgestellt habe: wenn ich jedes Feld mit REM (sinnvoll = was für eine Bedeutung hat das Feld) kommentiere, kann ich mir auf Knopfdruck einen schnellen Überblick verschaffen.

Eine weitere Idee ist auch das Hide-When in diese Dokumentation aufzunehmen (auch eine Sache, die man immer wieder bei der Maske durchgeht).  Leider ist das Hide-When im DXL nicht bei den Feldern gespeichert, sondern (wie zu erwarten war) bei den Absätzen in der Maske. Das Problem diese Beziehung automatisch auszulesen habe ich noch nicht gelöst.

@Marinero Atlántico

> Übersichtlichkeit kommt in eine Anwendung nicht durch Dokumentation sondern durch
> eine gute Architektur und ein gutes Design. Und für beides wurde Notes einfach nicht konzipiert.

Ich gebe dir recht, es ist eine Herausforderung  Stell dir vor du musst eine Notes-Anwendung von jemandem übernehmen (z.B. nach sechs Monaten von dir selbst ) und die Anwendung ist auf  'meine' Weise kommentiert: du kannst auf Knopfdruck einen ersten Überblick bekommen. Also, mir hat es geholfen.

Auf jeden Fall schon einmal vielen Dank für das Feedback.


Gruß
Christian

[cubetoon]

Sehr gute Idee, habe mich neulich erst gefragt wie man das mit der Doku antellt, wenn die Projekte einmal größer und umfangreicher werden ...
Nun hab ich hier das erste mal was von xsl-files gehört.
Bin streng nach Vorschrift vorgegangen. Dennoch sehe ich den Menüpunkt unter Tools DXL Utilities nicht den beschriebenen Menüpunkt - auch nicht nach Neustart des Client.
Was habe ich ich falsch gemacht.
cubetoon

[Marinero Atlántico]

Stell dir vor du musst eine Notes-Anwendung von jemandem übernehmen (z.B. nach sechs Monaten von dir selbst )

Stell dir vor ist gut.  Ich verdiene damit seit Monaten Geld.
Arbeite gerade daran, jegliches jammern zu stoppen.
Wenn einer sagt: Was? Sie brauchen 3 Tage, um diesen kleinen bug zu beheben?
Ich: Ja.
Und dann kommt zwischendurch immer mal wieder: In 2 Wochen starten wir aber richtig mit diesem Websphere Portal Projekt. Für das Notes haben wir kein Budget mehr.
Ich: Soll ich aufhören?
Sie: Nein.
Ehrlichgesagt ist es mir inzwischen egal, solange ich zu Hause mit Hibernate, Xdoclet und spring arbeiten kann.
Es existiert zwar im Management kein Bewußtsein für wirklich tief im Design versteckte, üble zu findene Bugs. Das aber nur auf der Oberfläche. Tritt man in entscheidenden Momenten ein bischen selbstbewußt auf, ahnen die was los ist.
Ich hab bei Kunden noch nie so eine Bereitschaft gespürt, Verträge zu verlängern wie dieses Jahr.

@Leute: In den nächsten 10 Jahren schreiben wir aber besser strukturiertere Anwendungen. Ok?
We can do much better.


Axel

[cgorni]

Hi,

@cubetoon
> Dennoch sehe ich den Menüpunkt unter Tools DXL Utilities nicht den beschriebenen Menüpunkt -
> auch nicht nach Neustart des Client.

Es ist der Menüpunkt "Transformer...". Der ist eigentlich nicht extra dazugekommen, sondern ist Standard im Notes 6 Designer Client (genauso wie "Exporter" und "Viewer").

Mein "Tool" fügt also dort keinen neuen Menüpunkt ein, sondern man wählt nach Auswahl "Transformer..." das Design Element und das Stylesheet aus, das für die Transformation benutzt werden soll (eins von meinen, je nach Design Element).

Hope that helps