SlideShare ist ein Scribd-Unternehmen logo
1 von 32
Downloaden Sie, um offline zu lesen
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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

Weitere ähnliche Inhalte

Ähnlich wie iDocIt - Ein Assistent zur API-Dokumentation

Leichtgewichtige API-Dokumentation – Ein Paradoxon?
Leichtgewichtige API-Dokumentation – Ein Paradoxon?Leichtgewichtige API-Dokumentation – Ein Paradoxon?
Leichtgewichtige API-Dokumentation – Ein Paradoxon?DeveloperConference
 
Data Vault DWH Automation
Data Vault DWH AutomationData Vault DWH Automation
Data Vault DWH AutomationTorsten Glunde
 
Domain Driven Design in Rails
Domain Driven Design in RailsDomain Driven Design in Rails
Domain Driven Design in RailsAngelo Maron
 
Ajax hands on - Refactoring Google Suggest
Ajax hands on - Refactoring Google SuggestAjax hands on - Refactoring Google Suggest
Ajax hands on - Refactoring Google SuggestBastian Feder
 
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“hpaustria
 
Systematische Konstruktion von API-Verträgen
Systematische Konstruktion von API-VerträgenSystematische Konstruktion von API-Verträgen
Systematische Konstruktion von API-VerträgenJan Christian Krause
 
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET CoreHands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET CoreGregor Biswanger
 
Django - The Web framework for perfectionists with deadlines
Django - The Web framework for perfectionists with deadlinesDjango - The Web framework for perfectionists with deadlines
Django - The Web framework for perfectionists with deadlinesMarkus Zapke-Gründemann
 
Barrierefreie, Java-Script gestützte Webapplikationen im praxisnahen Umfeld
Barrierefreie, Java-Script gestützte Webapplikationen im praxisnahen UmfeldBarrierefreie, Java-Script gestützte Webapplikationen im praxisnahen Umfeld
Barrierefreie, Java-Script gestützte Webapplikationen im praxisnahen Umfeldfelixnagel
 
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...Spark Summit
 
Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...
Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...
Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...Cristina Vidu
 
amsl - Ergebnispräsentation der EFRE-Förderphase
amsl - Ergebnispräsentation der EFRE-Förderphaseamsl - Ergebnispräsentation der EFRE-Förderphase
amsl - Ergebnispräsentation der EFRE-FörderphaseBjörn Muschall
 
AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...
AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...
AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...Amazon Web Services
 
chapter zürich rpa best practices
chapter zürich rpa best practiceschapter zürich rpa best practices
chapter zürich rpa best practicesCristina Vidu
 
Ist GraphQL das bessere REST
Ist GraphQL das bessere RESTIst GraphQL das bessere REST
Ist GraphQL das bessere RESTMartin Abraham
 
Clickstream Analysis with Spark
Clickstream Analysis with Spark Clickstream Analysis with Spark
Clickstream Analysis with Spark Josef Adersberger
 
Clickstream Analysis with Spark - Understanding Visitors in Real Time
Clickstream Analysis with Spark - Understanding Visitors in Real TimeClickstream Analysis with Spark - Understanding Visitors in Real Time
Clickstream Analysis with Spark - Understanding Visitors in Real TimeQAware GmbH
 

Ähnlich wie iDocIt - Ein Assistent zur API-Dokumentation (20)

Leichtgewichtige API-Dokumentation – Ein Paradoxon?
Leichtgewichtige API-Dokumentation – Ein Paradoxon?Leichtgewichtige API-Dokumentation – Ein Paradoxon?
Leichtgewichtige API-Dokumentation – Ein Paradoxon?
 
Data Vault DWH Automation
Data Vault DWH AutomationData Vault DWH Automation
Data Vault DWH Automation
 
Domain Driven Design in Rails
Domain Driven Design in RailsDomain Driven Design in Rails
Domain Driven Design in Rails
 
Ajax hands on - Refactoring Google Suggest
Ajax hands on - Refactoring Google SuggestAjax hands on - Refactoring Google Suggest
Ajax hands on - Refactoring Google Suggest
 
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
 
Systematische Konstruktion von API-Verträgen
Systematische Konstruktion von API-VerträgenSystematische Konstruktion von API-Verträgen
Systematische Konstruktion von API-Verträgen
 
Rails goes SOA
Rails goes SOARails goes SOA
Rails goes SOA
 
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET CoreHands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
 
Django - The Web framework for perfectionists with deadlines
Django - The Web framework for perfectionists with deadlinesDjango - The Web framework for perfectionists with deadlines
Django - The Web framework for perfectionists with deadlines
 
Barrierefreie, Java-Script gestützte Webapplikationen im praxisnahen Umfeld
Barrierefreie, Java-Script gestützte Webapplikationen im praxisnahen UmfeldBarrierefreie, Java-Script gestützte Webapplikationen im praxisnahen Umfeld
Barrierefreie, Java-Script gestützte Webapplikationen im praxisnahen Umfeld
 
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
 
Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...
Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...
Developer Best Practices (Robotic Enterprise Framework REF) – Anwendung und d...
 
amsl - Ergebnispräsentation der EFRE-Förderphase
amsl - Ergebnispräsentation der EFRE-Förderphaseamsl - Ergebnispräsentation der EFRE-Förderphase
amsl - Ergebnispräsentation der EFRE-Förderphase
 
AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...
AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...
AWS Initiate Berlin - Maschinelles Lernen - Chancen, Werkzeuge und Beispiel-A...
 
chapter zürich rpa best practices
chapter zürich rpa best practiceschapter zürich rpa best practices
chapter zürich rpa best practices
 
Elasticsearch Cluster Management mit Marvel
Elasticsearch Cluster Management mit MarvelElasticsearch Cluster Management mit Marvel
Elasticsearch Cluster Management mit Marvel
 
SciflowWriter
SciflowWriterSciflowWriter
SciflowWriter
 
Ist GraphQL das bessere REST
Ist GraphQL das bessere RESTIst GraphQL das bessere REST
Ist GraphQL das bessere REST
 
Clickstream Analysis with Spark
Clickstream Analysis with Spark Clickstream Analysis with Spark
Clickstream Analysis with Spark
 
Clickstream Analysis with Spark - Understanding Visitors in Real Time
Clickstream Analysis with Spark - Understanding Visitors in Real TimeClickstream Analysis with Spark - Understanding Visitors in Real Time
Clickstream Analysis with Spark - Understanding Visitors in Real Time
 

Mehr von Jan Christian Krause

Using Thematic Grids to Document Web Service Operations
Using Thematic Grids to Document Web Service OperationsUsing Thematic Grids to Document Web Service Operations
Using Thematic Grids to Document Web Service OperationsJan Christian Krause
 
Gut dokumentiert ist halb gesichert
Gut dokumentiert ist halb gesichertGut dokumentiert ist halb gesichert
Gut dokumentiert ist halb gesichertJan Christian Krause
 
Using Meaningful Names to Improve API Documentation
Using Meaningful Names to Improve API DocumentationUsing Meaningful Names to Improve API Documentation
Using Meaningful Names to Improve API DocumentationJan Christian Krause
 
Mut zur Lücke - Werkzeuge zur alltagstauglichen Dokumentation
Mut zur Lücke - Werkzeuge zur alltagstauglichen DokumentationMut zur Lücke - Werkzeuge zur alltagstauglichen Dokumentation
Mut zur Lücke - Werkzeuge zur alltagstauglichen DokumentationJan Christian Krause
 

Mehr von Jan Christian Krause (6)

Using Thematic Grids to Document Web Service Operations
Using Thematic Grids to Document Web Service OperationsUsing Thematic Grids to Document Web Service Operations
Using Thematic Grids to Document Web Service Operations
 
Gut dokumentiert ist halb gesichert
Gut dokumentiert ist halb gesichertGut dokumentiert ist halb gesichert
Gut dokumentiert ist halb gesichert
 
Using Meaningful Names to Improve API Documentation
Using Meaningful Names to Improve API DocumentationUsing Meaningful Names to Improve API Documentation
Using Meaningful Names to Improve API Documentation
 
Master - Und was dann?
Master  - Und was dann?Master  - Und was dann?
Master - Und was dann?
 
Nur Schall und Rauch?
Nur Schall und Rauch?Nur Schall und Rauch?
Nur Schall und Rauch?
 
Mut zur Lücke - Werkzeuge zur alltagstauglichen Dokumentation
Mut zur Lücke - Werkzeuge zur alltagstauglichen DokumentationMut zur Lücke - Werkzeuge zur alltagstauglichen Dokumentation
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