iDocIt - Ein Assistent zur API-Dokumentation
-
Upload
jan-christian-krause -
Category
Software
-
view
38 -
download
0
Transcript of iDocIt - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
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
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Agenda
Motivation
API-Dokumentation mit iDocIt!Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!
Thematische Rollen und Raster fur Web ServicesVorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Fallbeispiel
Fazit und Ausblick
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Motivation - Cartoon I
Fur Quelle siehe letzte FolieJan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Motivation - Cartoon II
Fur Quelle siehe letzte FolieJan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Motivation - Fragen
I Ist der Code die Dokumentation?
I Worin besteht der Aufwand beim Dokumentieren?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!
Metaphern Stille und Rauschen
I Stille:Stille: Relevanter Aspekt der Operation, der in derDokumentation nicht erwahnt wird
I Rauschen:Irrelevante, redundante, nicht aktuelle oder unnotigausfuhrliche Dokumentation zu einem Aspekt der Operation
I Stille und Rauschen erzeugen Aufwand bei der Erstellung undbei der Konsultation von API-Dokumentation
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!
Reminder: API-Dokumentation mit thematischen Rastern
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!
iDocIt! - Ein Werkzeug zur API-Dokumentation
I Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoff(AKRA GmbH)
I Eclipse Plugin (mind. Version 3.6)
I Dynamische Hinweise auf Stille
I Unterstutzt derzeit WSDL und Java (Erweiterbar um weitereProgrammier- und Markupsprachen (als Eclipse-Plugins))
I Open Source-Projekt bei Google Code(http://idocit.googlecode.com/)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Metaphern Stille und RauschenReminder: API-Dokumentation mit thematischen RasterniDocIt!
Live-Demo von iDocIt!
Live-Demo
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Vorbemerkungen
I iDocIt! benotigt thematische Rollen und Raster zurErkennung von Stille
I Thematische Rollen und Raster wurden empirisch auf Basisdes seekda-Corpus ermittelt.
Beschreibung Wert
Anzahl Dienstanbieter 8.947Anzahl WSDL-Beschreibungen 17.453Anzahl Port Types 24.474Anzahl Operationen 186.736
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Vorgehensweise
1. Erstelle eine Liste aller Operationen und entferne Dubletten.
2. Mische die Liste zufallig und spalte sie in Pakete mit je 50Operationen auf (Bezeichner, vollst. Input-, sowieOutput-Message und Faults).
3. Annotiere jedes Signaturelement jeder Operation mit einerthematischen Rolle (definiere ggf. eine passende Rolle). Initialwerden die 14 von Girardi und Ibrahim identifzierten Rollenvewendet.
4. Erfasse pro Paket die Anzahl der neu identifiziertenthematischen Rollen. Analysiere solange neue Pakete, bis derRollenzuwachs drei Mal 5% oder weniger betragt.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Sattigungskurve
Corpus Große [Anzahl Pakete]
Th
emat
isch
eR
olle
n
0 1 2 3 4 5 610
20
30
40
50
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Tabelle
Paket∑
Rollen Neue Rollen Zuwachs [%] Ign. Operationen
0 14 14 0 01 31 17 1,21 12 37 6 0,19 23 42 5 0,14 14 44 2 0,05 25 44 0 0,00 26 45 1 0,02 5
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Beispiele
I ALGORITHM: Set of instructions how to perform theACTION.
I FORMULA: Formula used to compute a value during theACTION.
I OPERAND: Argument of a FORMULA.I ORDERING: The ordering of the returned OBJECTs.I LIMIT: The entity used to limit the ACTIONs space (e.g.
number of OBJECTs to return).I FORMAT: The format of the OBJECT processed by an
ACTION.I SOURCE FORMAT: The FORMAT of the SOURCE.I ACCESS: How the OBJECT of an ACTION could be
accessed.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Zusammenfassung
I iDocIt! verfugt initial uber 45 thematische Rollen (14 vonGirardi und Ibrahim + 31 aus dem seekda-Corpus)
I Thematische Rollen konnen generalisier- und spezialisierbarsein (z.B. FORMAT und SOURCE FORMAT)
I Thematischen Rollen hangen nicht nur vom Pradikat ab (z.B.ORDERING vom Numerus des OBJECT)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Vorgehensweise
1. Klassifiziere das als ACTION annotierte Pradikat jederOperation in VerbNet.
2. Ordne alle thematische Rollen der Operation denentsprechenden VerbNet-Kategorien zu.
3. Erprobe die so ermittelten thematischen Raster in Projektenund passe sie ggf. manuell an.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Detailliertes Beispiel
Searching OperationsA searching operation searches for one or many OBJECTs at aSOURCE. The searched OBJECTs are identified by one or manyCOMPARISONs or PRIMARY KEYs. The number of foundOBJECTs could be limited by specifying a LIMIT. In case of manyOBJECTs an ORDERING defines their arrangement. TheALGORITHM defines the way the OBJECTs are searched. Thiscategory bases on the VerbNet classes Search-35.2 andobtain-13.5.2.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Weitere Beispiele
I Checking Operations
I Converting Operations
I Creating Operations
I Describing Operations
I Duplicating Operations
I Establishing Operations
I Getting Operations
I Mathematical Operations
I Merging Operations
I Putting Operations
I Removing Operations
I Sending Operations
I Starting Operations
I Substituting Operations
I Throwing Operations
I Traversing Operations
I Initializing Operations
I Loading Operations
I Sorting Operations
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Zusammenfassung
I Identifikation von 17 thematischen Rastern fur Web Services
I Praktischer Einsatz erbrachte drei weitere Raster
Zur Erinnerung:
I Ziel von iDocIt! ist die Vereinfachung von API-Dokumentation
I Wie kann die Komplexitat thematischer Raster und Rollenbeherrschbar gemacht werden?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Rollen und rasterbasierte Regeln
I Grundkonzept: Steuerung der Empfehlung thematischerRollen durch Regeln.
I Auswertungskontext ist immer die Operation, sowie alle ihrubergeordneten und untergeordneten Signaturelemente.
I Rollenbasierte Regeln:Steuerungsregeln als Eigenschaft einer thematischen Rolle
I Rasterbasierte Regeln:Steuerungsregeln als rollenspezifische Eigenschaft einesthematischen Rasters
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Rollenbasierte Regeln
I Gegeben: das zu dokumentierende Signaturelement
I Frage: Soll die jeweilige thematische Rolle zurDokumentation angeboten werden?
I Aktuelle Implementierung iDocIt!:
I Fur jede Rolle ist definiert, auf welchen Ebenen sie zurDokumentation empfohlen wird.
I Ebenen sind: Interface (relevant fur AGENT), Operation(relevant fur ACTION) oder beides (Default)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Rasterbasierte Regeln
I Gegeben: das zu dokumentierende Signaturelement und dasthematische Raster (Referenzraster)
I Frage: Soll die jeweilige thematische Rolle zurDokumentation angeboten werden?
I Aktuelle Implementierung iDocIt!:
I Fur jede Rolle eines Rasters existiert eine pradikatenlogischeFormel, die die Empfehlung der Rolle steuert.
I Mogliche Pradikate in dieser Formel sind:
I isSingular(”ROLLE”)I isPlural(”ROLLE”)
I exists(”ROLLE”)I hasAttributes(”ROLLE”)
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Beispiel zu rasterbasierten Regeln
Searching OperationsRolle 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
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Weiteres Beispiel zu rasterbasierten Regeln
Creating OperationsRolle 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
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
VorbemerkungenThematische RollenThematische RasterRollen und rasterbasierte Regeln
Live-Demo von rollen- und rasterbasierten Regeln
Live-Demo
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Analyse der Ebay Trading API
I Ebay bietet Web Service zur Integration von Ebay-Diensten inAnwendungen
I Analysiert wird die Operation getFeedback(...)
I Ziel: Identifikation von Stille und Rauschen
I Nutzung von iDocIt! als Analyse-Werkzeug
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Ergebnisse I
Stille:
I Sortierung der zuruckgelieferten Bewertungen ist nichtspezifiziert [them. Rolle ORDERING]
I Unterschiedliche Datenquellen (Sandbox- undProduktivumgebung) sind nur unzureichend dargestellt [them.Rolle SOURCE]
I Berechnungsvorschrift fur die Feedback-Punktzahl ist nichtdokumentiert (findet sich an anderer Stelle in der EbayOnline-Hilfe) [them. Rolle FORMULA]
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Ergebnisse I
Rauschen:
I Vermeidung von Redundanz durch Nutzung der RollePRIMARY KEY fur ID- Felder (z.B. FeedbackID)
I Durch Anwendung des Lokalitatsprinzips bzgl.Felddokumentation lasst sich viel Rauschen der Kategorie 2einsparen, z.B. bei Feld DetailLevel.
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Fazit
Fazit:
I Thematische Raster konnen helfen Stille und Rauschen zuvermeiden
I Voraussetzung sind prazise gewahlte Verben in denOperationsbezeichnern
I Kardinalitaten thematischer Rollen sind nicht ableitbar
I AKRA sammelt Erfahrungen mit diesem Verfahren inmehreren Projekten
I Offen bleibt: wie viel Dokumentation schafft wirklichenMehrwert?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Fazit
Ausblick:
I Empirischer Nachweis der Qualitatssteigerung durch iDocIt!
I Zukunftiger Forschungsschwerpunkt: Beschreibung vonAktivitaten in Prozessmodellen mit Hilfe thematischer Raster
I Automatische Belegung thematischer Raster mitdokumentierten, naturlichsprachlichen Inhalten
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Diskussion
Vielen Dank fur Ihre Aufmerksamkeit.Haben Sie Anmerkungen, Fragen oder Kritik?
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation
MotivationAPI-Dokumentation mit iDocIt!
Thematische Rollen und Raster fur Web ServicesFallbeispiel
Fazit und Ausblick
Quellen
Quellen:
I Cartoon I: Widder, Oliver: ”Software Documentation?”;veroffentlicht auf http://itmanagement.earthweb.com
I Cartoon II: Widder, Oliver: ”Behind the Code?”;veroffentlicht auf http://itmanagement.earthweb.com
Jan Christian Krause(AKRA GmbH) iDocIt! - Ein Assistent zur API-Dokumentation