Foliensatz zu meinem Vortrag im Oberseminar des Arbeitsbereiches Natürlichsprachliche Systeme (NatS) am Dep. Informatik der Universität Hamburg vom 29.11.2011
Mut zur Lücke - Werkzeuge zur alltagstauglichen Dokumentation
iDocIt - Ein Assistent zur API-Dokumentation
1. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
iDocIt! - Ein Assistent zur API-Dokumentation
Jan Christian Krause
(AKRA GmbH)
NatS / WSV Oberseminar am 29.11.2011
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
2. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Agenda
Motivation
API-Dokumentation mit iDocIt!
Metaphern Stille und Rauschen
Reminder: API-Dokumentation mit thematischen Rastern
iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Fallbeispiel
Fazit und Ausblick
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
3. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Motivation - Cartoon I
F¨ur Quelle siehe letzte Folie
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
4. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Motivation - Cartoon II
F¨ur Quelle siehe letzte Folie
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
5. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Motivation - Fragen
Ist der Code die Dokumentation?
Worin besteht der Aufwand beim Dokumentieren?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
6. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Metaphern Stille und Rauschen
Reminder: API-Dokumentation mit thematischen Rastern
iDocIt!
Metaphern Stille und Rauschen
Stille:
Stille: Relevanter Aspekt der Operation, der in der
Dokumentation nicht erw¨ahnt wird
Rauschen:
Irrelevante, redundante, nicht aktuelle oder unn¨otig
ausf¨uhrliche Dokumentation zu einem Aspekt der Operation
Stille und Rauschen erzeugen Aufwand bei der Erstellung und
bei der Konsultation von API-Dokumentation
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
7. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Metaphern Stille und Rauschen
Reminder: API-Dokumentation mit thematischen Rastern
iDocIt!
Reminder: API-Dokumentation mit thematischen Rastern
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
8. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Metaphern Stille und Rauschen
Reminder: API-Dokumentation mit thematischen Rastern
iDocIt!
iDocIt! - Ein Werkzeug zur API-Dokumentation
Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoff
(AKRA GmbH)
Eclipse Plugin (mind. Version 3.6)
Dynamische Hinweise auf Stille
Unterst¨utzt derzeit WSDL und Java (Erweiterbar um weitere
Programmier- und Markupsprachen (als Eclipse-Plugins))
Open Source-Projekt bei Google Code
(http://idocit.googlecode.com/)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
9. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Metaphern Stille und Rauschen
Reminder: API-Dokumentation mit thematischen Rastern
iDocIt!
Live-Demo von iDocIt!
Live-Demo
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
10. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Vorbemerkungen
iDocIt! ben¨otigt thematische Rollen und Raster zur
Erkennung von Stille
Thematische Rollen und Raster wurden empirisch auf Basis
des seekda-Corpus ermittelt.
Beschreibung Wert
Anzahl Dienstanbieter 8.947
Anzahl WSDL-Beschreibungen 17.453
Anzahl Port Types 24.474
Anzahl Operationen 186.736
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
11. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Vorgehensweise
1. Erstelle eine Liste aller Operationen und entferne Dubletten.
2. Mische die Liste zuf¨allig und spalte sie in Pakete mit je 50
Operationen auf (Bezeichner, vollst. Input-, sowie
Output-Message und Faults).
3. Annotiere jedes Signaturelement jeder Operation mit einer
thematischen Rolle (definiere ggf. eine passende Rolle). Initial
werden die 14 von Girardi und Ibrahim identifzierten Rollen
vewendet.
4. Erfasse pro Paket die Anzahl der neu identifizierten
thematischen Rollen. Analysiere solange neue Pakete, bis der
Rollenzuwachs drei Mal 5% oder weniger betr¨agt.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
12. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
S¨attigungskurve
Corpus Gr¨oße [Anzahl Pakete]
ThematischeRollen
0 1 2 3 4 5 6
10
20
30
40
50
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
13. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Tabelle
Paket Rollen Neue Rollen Zuwachs [%] Ign. Operationen
0 14 14 0 0
1 31 17 1,21 1
2 37 6 0,19 2
3 42 5 0,14 1
4 44 2 0,05 2
5 44 0 0,00 2
6 45 1 0,02 5
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
14. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Beispiele
ALGORITHM: Set of instructions how to perform the
ACTION.
FORMULA: Formula used to compute a value during the
ACTION.
OPERAND: Argument of a FORMULA.
ORDERING: The ordering of the returned OBJECTs.
LIMIT: The entity used to limit the ACTIONs space (e.g.
number of OBJECTs to return).
FORMAT: The format of the OBJECT processed by an
ACTION.
SOURCE FORMAT: The FORMAT of the SOURCE.
ACCESS: How the OBJECT of an ACTION could be
accessed.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
15. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Zusammenfassung
iDocIt! verf¨ugt initial ¨uber 45 thematische Rollen (14 von
Girardi und Ibrahim + 31 aus dem seekda-Corpus)
Thematische Rollen k¨onnen generalisier- und spezialisierbar
sein (z.B. FORMAT und SOURCE FORMAT)
Thematischen Rollen h¨angen nicht nur vom Pr¨adikat ab (z.B.
ORDERING vom Numerus des OBJECT)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
16. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Vorgehensweise
1. Klassifiziere das als ACTION annotierte Pr¨adikat jeder
Operation in VerbNet.
2. Ordne alle thematische Rollen der Operation den
entsprechenden VerbNet-Kategorien zu.
3. Erprobe die so ermittelten thematischen Raster in Projekten
und passe sie ggf. manuell an.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
17. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Detailliertes Beispiel
Searching Operations
A searching operation searches for one or many OBJECTs at a
SOURCE. The searched OBJECTs are identified by one or many
COMPARISONs or PRIMARY KEYs. The number of found
OBJECTs could be limited by specifying a LIMIT. In case of many
OBJECTs an ORDERING defines their arrangement. The
ALGORITHM defines the way the OBJECTs are searched. This
category bases on the VerbNet classes Search-35.2 and
obtain-13.5.2.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
18. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Weitere Beispiele
Checking Operations
Converting Operations
Creating Operations
Describing Operations
Duplicating Operations
Establishing Operations
Getting Operations
Mathematical Operations
Merging Operations
Putting Operations
Removing Operations
Sending Operations
Starting Operations
Substituting Operations
Throwing Operations
Traversing Operations
Initializing Operations
Loading Operations
Sorting Operations
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
19. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Zusammenfassung
Identifikation von 17 thematischen Rastern f¨ur Web Services
Praktischer Einsatz erbrachte drei weitere Raster
Zur Erinnerung:
Ziel von iDocIt! ist die Vereinfachung von API-Dokumentation
Wie kann die Komplexit¨at thematischer Raster und Rollen
beherrschbar gemacht werden?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
20. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Rollen und rasterbasierte Regeln
Grundkonzept: Steuerung der Empfehlung thematischer
Rollen durch Regeln.
Auswertungskontext ist immer die Operation, sowie alle ihr
¨ubergeordneten und untergeordneten Signaturelemente.
Rollenbasierte Regeln:
Steuerungsregeln als Eigenschaft einer thematischen Rolle
Rasterbasierte Regeln:
Steuerungsregeln als rollenspezifische Eigenschaft eines
thematischen Rasters
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
21. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Rollenbasierte Regeln
Gegeben: das zu dokumentierende Signaturelement
Frage: Soll die jeweilige thematische Rolle zur
Dokumentation angeboten werden?
Aktuelle Implementierung iDocIt!:
F¨ur jede Rolle ist definiert, auf welchen Ebenen sie zur
Dokumentation empfohlen wird.
Ebenen sind: Interface (relevant f¨ur AGENT), Operation
(relevant f¨ur ACTION) oder beides (Default)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
22. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Rasterbasierte Regeln
Gegeben: das zu dokumentierende Signaturelement und das
thematische Raster (Referenzraster)
Frage: Soll die jeweilige thematische Rolle zur
Dokumentation angeboten werden?
Aktuelle Implementierung iDocIt!:
F¨ur jede Rolle eines Rasters existiert eine pr¨adikatenlogische
Formel, die die Empfehlung der Rolle steuert.
M¨ogliche Pr¨adikate in dieser Formel sind:
isSingular(”ROLLE”)
isPlural(”ROLLE”)
exists(”ROLLE”)
hasAttributes(”ROLLE”)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
23. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Beispiel zu rasterbasierten Regeln
Searching Operations
Rolle Status Zeige Rolle wenn ...
ACTION man immer()
AGENT man immer()
ALGORITHM opt immer()
COMPARISON opt !exists(”PRIMARY KEY”)
LIMIT opt isPlural(”OBJECT”)
OBJECT man immer()
ORDERING opt isPlural(”OBJECT”)
PRIMARY KEY opt !exists(”COMPARISON”)
SOURCE man immer()
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
24. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Weiteres Beispiel zu rasterbasierten Regeln
Creating Operations
Rolle Status Zeige Rolle wenn ...
ACTION man immer()
AGENT man immer()
ATTRIBUTE opt hasAttributes(”OBJECT”)
DESTINATION man immer()
NAME opt !exists(”PRIMARY KEY”)
OWNER opt immer()
OBJECT man immer()
PRIMARY KEY opt !exists(”NAME”)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
25. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Vorbemerkungen
Thematische Rollen
Thematische Raster
Rollen und rasterbasierte Regeln
Live-Demo von rollen- und rasterbasierten Regeln
Live-Demo
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
26. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Analyse der Ebay Trading API
Ebay bietet Web Service zur Integration von Ebay-Diensten in
Anwendungen
Analysiert wird die Operation getFeedback(...)
Ziel: Identifikation von Stille und Rauschen
Nutzung von iDocIt! als Analyse-Werkzeug
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
27. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Ergebnisse I
Stille:
Sortierung der zur¨uckgelieferten Bewertungen ist nicht
spezifiziert [them. Rolle ORDERING]
Unterschiedliche Datenquellen (Sandbox- und
Produktivumgebung) sind nur unzureichend dargestellt [them.
Rolle SOURCE]
Berechnungsvorschrift f¨ur die Feedback-Punktzahl ist nicht
dokumentiert (findet sich an anderer Stelle in der Ebay
Online-Hilfe) [them. Rolle FORMULA]
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
28. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Ergebnisse I
Rauschen:
Vermeidung von Redundanz durch Nutzung der Rolle
PRIMARY KEY f¨ur ID- Felder (z.B. FeedbackID)
Durch Anwendung des Lokalit¨atsprinzips bzgl.
Felddokumentation l¨asst sich viel Rauschen der Kategorie 2
einsparen, z.B. bei Feld DetailLevel.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
29. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Fazit
Fazit:
Thematische Raster k¨onnen helfen Stille und Rauschen zu
vermeiden
Voraussetzung sind pr¨azise gew¨ahlte Verben in den
Operationsbezeichnern
Kardinalit¨aten thematischer Rollen sind nicht ableitbar
AKRA sammelt Erfahrungen mit diesem Verfahren in
mehreren Projekten
Offen bleibt: wie viel Dokumentation schafft wirklichen
Mehrwert?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
30. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Fazit
Ausblick:
Empirischer Nachweis der Qualit¨atssteigerung durch iDocIt!
Zuk¨unftiger Forschungsschwerpunkt: Beschreibung von
Aktivit¨aten in Prozessmodellen mit Hilfe thematischer Raster
Automatische Belegung thematischer Raster mit
dokumentierten, nat¨urlichsprachlichen Inhalten
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
31. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Diskussion
Vielen Dank f¨ur Ihre Aufmerksamkeit.
Haben Sie Anmerkungen, Fragen oder Kritik?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
32. Motivation
API-Dokumentation mit iDocIt!
Thematische Rollen und Raster f¨ur Web Services
Fallbeispiel
Fazit und Ausblick
Quellen
Quellen:
Cartoon I: Widder, Oliver: ”Software Documentation?”;
ver¨offentlicht auf http://itmanagement.earthweb.com
Cartoon II: Widder, Oliver: ”Behind the Code?”;
ver¨offentlicht auf http://itmanagement.earthweb.com
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation