Foliensatz zu meinem Vortrag im Oberseminar des Arbeitsbereiches Natürlichsprachliche Systeme (NatS) am Dep. Informatik der Universität Hamburg vom 29.11.2011
The document discusses using thematic grids to document web service operations. It proposes that a web service operation's understanding is determined by its identifier, consumed resources, and exchangeable behavior specifications. Currently, documentation grids only describe interaction elements, not resources or strategies. Thematic grids derived from a verb's meaning and roles could help identify hidden resources and strategies by associating operation parameters and roles. An empirical analysis found most operation identifiers contain verbs classified by semantic classes with thematic grids. Next steps involve defining appropriate thematic roles, extending WSDL to support documentation with grids, and creating an assistant for thematic grid documentation.
Presentation of my colleague Benjamin Pfänder and mine at the Code Talks 2016-conference in Hamburg. Our talk was about the benefits of software architecture-documentation for a threat analysis.
Bei der Erstellung von API-Dokumentation besteht die Gefahr, dass relevante Informationen fehlen und irrelevante enthalten sind. Das Lesen dieser Art von Dokumentation ist aufwändig, u.U. nicht zielführend und kostet daher unnötig Zeit – und zwar für Autor und Leser. Dieser Vortrag diskutiert Ursachen dafür und zeigt, wie Lücken und irrelevante Aspekte in API-Dokumentation erkannt und vermieden werden können. Auf diese Weise kann die Pflege und Nutzung von API-Dokumentation trotz eines stressigen Projektalltags möglich werden.
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“hpaustria
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“
Presentation from HEROLD (www.herold.at) at the HP Ideas 2008 in Vienna/Austria.
http://www.herold.at
http://hpideas.wordpress.com
http://www.hp.com/at/ideas
Foliensatz zu meinem Vortrag im Oberseminar des Arbeitsbereiches Natürlichsprachliche Systeme (NatS) am Dep. Informatik der Universität Hamburg vom 29.11.2011
The document discusses using thematic grids to document web service operations. It proposes that a web service operation's understanding is determined by its identifier, consumed resources, and exchangeable behavior specifications. Currently, documentation grids only describe interaction elements, not resources or strategies. Thematic grids derived from a verb's meaning and roles could help identify hidden resources and strategies by associating operation parameters and roles. An empirical analysis found most operation identifiers contain verbs classified by semantic classes with thematic grids. Next steps involve defining appropriate thematic roles, extending WSDL to support documentation with grids, and creating an assistant for thematic grid documentation.
Presentation of my colleague Benjamin Pfänder and mine at the Code Talks 2016-conference in Hamburg. Our talk was about the benefits of software architecture-documentation for a threat analysis.
Bei der Erstellung von API-Dokumentation besteht die Gefahr, dass relevante Informationen fehlen und irrelevante enthalten sind. Das Lesen dieser Art von Dokumentation ist aufwändig, u.U. nicht zielführend und kostet daher unnötig Zeit – und zwar für Autor und Leser. Dieser Vortrag diskutiert Ursachen dafür und zeigt, wie Lücken und irrelevante Aspekte in API-Dokumentation erkannt und vermieden werden können. Auf diese Weise kann die Pflege und Nutzung von API-Dokumentation trotz eines stressigen Projektalltags möglich werden.
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“hpaustria
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“
Presentation from HEROLD (www.herold.at) at the HP Ideas 2008 in Vienna/Austria.
http://www.herold.at
http://hpideas.wordpress.com
http://www.hp.com/at/ideas
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...Gregor Biswanger
Das Jahr 2009 war die Geburtsstunde von Node.js. Dass hierbei JavaScript ebenfalls serverseitig verwendet werden kann, ist nur ein Teilaspekt für den hohen Erfolg. Viel relevanter ist die extrem hohe Performance, Skalierbarkeit und Produktivität. Nicht ohne Grund wird ASP.NET komplett neu erfunden und basiert auf den gleichen Ideen wie Node.js. Namenhafte Firmen wie Microsoft selbst, Google, PayPal, New York Times, GitHub, uvw. setzen bereits auf das leistungsstarke Node.js. Der Vortrag zeigt durch eine Reise der Node.js Architektur, woher die Vorteile kommen. Durch einen Vergleich von ähnlichen Funktionen, wird zudem der ideale Einstieg für .NET Entwickler geboten.
Security Scanner Design am Beispiel von httpreconMarc Ruef
Am 24. September 2009 hielt Marc Ruef (CTO der scip AG) einen Vortrag an der OpenExpo 2009 in Winterthur. Dieser trug den Titel Security Scanner Design am Beispiel von httprecon und sollte drei Aspekte besprechen:
* Grundlegende Funktionsweise von Security Scanner
* Ideale Umsetzung einer entsprechenden Lösung
* Konkreter Vergleich zum httprecon project mit seinen Vor- und Nachteilen
Link: http://www.scip.ch/?labs.20090925
Das kleine Einmaleins der sicheren Architektur @heise_devSecMario-Leander Reimer
Sicherheit ist leider immer noch eine allzu häufig vernachlässigte nicht-funktionale Eigenschaft heutiger IT-Systeme. Auftraggeber haben oft nur die implizite Erwartung an ein sicheres System. Wir als Entwickler konzipieren und bauen aber genau das, was explizit gefordert wurde. Mit manchmal unangenehmen Konsequenzen.
Das Nachrüsten von Sicherheit in ein bestehendes System ist arbeitsintensiv, zeitaufwändig und teuer. Einfacher ist es, die Sicherheit bereits vom ersten Tag an mit zu berücksichtigen. Hört sich schwierig an? Das muss nicht sein.
Dieser Vortrag präsentiert einfache Regeln, Tools, Technologien und Entwurfsmuster für sichere Systemarchitekturen, die ein sicherheitsorientierter Entwickler oder Architekt definitiv kennen sollte. @heise_devSec @qaware #heisedevsec
Das kleine Einmaleins der sicheren ArchitekturQAware GmbH
//heise devSec() 2017, Heidelberg: Vortrag von Mario-Leander Reimer (@LeanderReimer, Cheftechnologe bei QAware) und Simon Bäumler (Softwarearchitekt bei QAware).
Abstract: Sicherheit ist leider immer noch eine allzu häufig vernachlässigte nicht-funktionale Eigenschaft heutiger IT-Systeme. Auftraggeber haben oft nur die implizite Erwartung an ein sicheres System. Wir als Entwickler konzipieren und bauen aber genau das, was explizit gefordert wurde. Mit manchmal unangenehmen Konsequenzen.
Das Nachrüsten von Sicherheit in ein bestehendes System ist arbeitsintensiv, zeitaufwändig und teuer. Einfacher ist es, die Sicherheit bereits vom ersten Tag an mit zu berücksichtigen. Hört sich schwierig an? Das muss nicht sein.
Dieser Vortrag präsentiert einfache Regeln, Tools, Technologien und Entwurfsmuster für sichere Systemarchitekturen, die ein sicherheitsorientierter Entwickler oder Architekt definitiv kennen sollte.
Im Rechenzentrum ist nicht nur ein einzelner Datenbankadministrator für die Verfügbarkeit der Daten verantwortlich. Der Vortrag von Senior Consultant Andreas Reinhardt (OPITZ CONSULTING) zeigt Faktoren, die zur Vermeidung von Datenverlust und zur schnellstmöglichen Datenwiederherstellung beitragen können. Betrachtet werden die Herausforderungen und die Kommunikation im Rechenzentrumsbetrieb sowie das technische Konzept zur Sicherung und Wiederherstellung der Daten.
Professionelle Anforderungsanalyse am Beispiel einer Java-Anwendung zur Betri...GFU Cyrus AG
Der Erfolg von Softwareentwicklungsprojekten hängt maßgeblich von einer guten Anforderungsanalyse ab. Je später Konzeptionsfehler erkannt werden, desto höher sind die Kosten der erforderlichen Korrekturen. Wir stellen in diesem Vortrag dar, wie durch eine strukturierte und dabei nicht zu formale Vorgehensweise frühzeitig sichergestellt werden kann, dass die später entwickelte Anwendung den Wünschen des Auftraggebers entspricht und zudem eine verlässliche Basis für die Einschätzung des Entwicklungsaufwands entsteht.
Im Vortrag verdeutlichen wir die Vorgehensweise an dem Beispiel einer Konzeption eines Systems zur Betriebsdatenerfassung und Leistungsentlohnung. Mit einem Mix aus Office- und UML-Werkzeugen konnte hier in kurzer Zeit ein gemeinsames Verständnis mit der Fachabteilung des Kunden erreicht werden und die formale Basis für die nachfolgende Realisierung des Systems geschaffen werden.
Auswahl von Werkzeugen aus dem Office- und Modellierungsumfeld
Halbformale Beschreibung von Anwendungsfällen
Erstellung eines fachlichen und technischen Glossars
Komponentenmodellierung mit UML
Entwicklung eines Anwendungs-Prototyps
Dataservices - Data Processing mit MicroservicesQAware GmbH
IT-Tage 2018, Frankfurt: Vortrag von Mario-Leander Reimer (@LeanderReimer, Cheftechnologe bei QAware)
=== Dokument bitte herunterladen für bessere Lesbarkeit! ===
Abstract: Data Processing und Microservices sind ein perfektes Gespann. In dieser Kombination können Microservices dazu verwendet werden, ein flexibles, Event-getriebenes und skalierbares System von lose gekoppelten Datenverarbeitungsaufgaben aufzubauen. Diesen Ansatz nennen wir Dataservices.
In diesem Vortrag stellen wir zunächst die wesentlichen Konzepte und einige Schlüsseltechnologien vor, um Dataservice-Architekturen zu realisieren. Anschließend werden wir die einzelnen Bestandteile einer exemplarischen Datenverarbeitungs-Pipeline schrittweise komponieren und die Showcase-Pipeline in der Cloud zur Ausführung bringen und skalieren.
Apache DeviceMap - Mobile Geräteerkennung für Java EE - JavaLand 2014Werner Keil
Das Wachstum an Mobiltelefonen, Tablets und ähnlichen Geräten, die den Markt geradezu überschwemmen erleben wir Tag für Tag.
Die Spezifikation jedes Einzelnen genau zu verfolgen ist ein Knochenjob. Diese Mühe kann reduziert werden, wenn zur Verbesserung dasDevice Description Repository – kurz DDR - beigesteuert wird und Anwender dieses selbst verwaltet können.
Apache DeviceMap enstand als Kooperation von Adobe, OpenDDR und anderen, um ein umfassendes Open Source Daten-Repository mit Geräteinformationen, Bilder und andere relevante Informationen für alle Arten von mobilen Geräten zu schaffen, Smartphones, Tablets, Smart-TV, u.dgl.
Das Projekt begann im Januar 2012, im Herbst 2012 wurden DDR APis für Java und .NET von OpenDDR beigesteuert. Die nächsten Schritte sind ein gemeinschaftliches Device Repository, eine Speicher-Struktur, die langfristige Erhaltung und Pflege dieser Daten durch die Apache Gemeinde erlaubt, unter Nutzung geläufiger Formate, wahrscheinlich JSON und / oder XML.
Slides zu meinem Talk beim Entwicklertag 2015 in Karlsruhe.
# Zusammenfassung
Sicherheit von Web-Anwendungen ist ein heißes Thema. Obwohl seit Jahren aktuell, werden die Meldungen über erneute Lücken gefühlt eher schlimmer als besser. Der Trend zu Single-Page-Anwendungen bringt für uns Entwickler eine ganze Reihe neuer Herausforderungen in punkto Sicherheit mit sich, da immer mehr Funktionalität in den Browser verlagert wird und dadurch mehr Code in nicht vertrauenswürdiger Umgebung läuft.
In diesem Talk wir anhand von AngularJS gezeigt auf was man bei SPAs achten muss. Anhand von Code-Beispielen wird natürlich auch gezeigt wie man sich z.B. vor Cross-Site-Scripting, Cross-Site-Request-Forgery und Code-Injection schützt und welche Gefahren sonst noch so lauern.
# Kurz-Bio
Philipp Burgmer studierte an der Hochschule Karlsruhe Informatik und arbeitet als Entwickler, Berater und [Trainer](http://thecodecampus.de) für die [w11k GmbH](http://w11k.de). Er ist Experte für Webtechnologien und beschäftigt sich mit der Gestaltung und Optimierung von Benutzeroberflächen. Privat interessiert er sich für Klettern und DJing.
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...Gregor Biswanger
Das Jahr 2009 war die Geburtsstunde von Node.js. Dass hierbei JavaScript ebenfalls serverseitig verwendet werden kann, ist nur ein Teilaspekt für den hohen Erfolg. Viel relevanter ist die extrem hohe Performance, Skalierbarkeit und Produktivität. Nicht ohne Grund wird ASP.NET komplett neu erfunden und basiert auf den gleichen Ideen wie Node.js. Namenhafte Firmen wie Microsoft selbst, Google, PayPal, New York Times, GitHub, uvw. setzen bereits auf das leistungsstarke Node.js. Der Vortrag zeigt durch eine Reise der Node.js Architektur, woher die Vorteile kommen. Durch einen Vergleich von ähnlichen Funktionen, wird zudem der ideale Einstieg für .NET Entwickler geboten.
Security Scanner Design am Beispiel von httpreconMarc Ruef
Am 24. September 2009 hielt Marc Ruef (CTO der scip AG) einen Vortrag an der OpenExpo 2009 in Winterthur. Dieser trug den Titel Security Scanner Design am Beispiel von httprecon und sollte drei Aspekte besprechen:
* Grundlegende Funktionsweise von Security Scanner
* Ideale Umsetzung einer entsprechenden Lösung
* Konkreter Vergleich zum httprecon project mit seinen Vor- und Nachteilen
Link: http://www.scip.ch/?labs.20090925
Das kleine Einmaleins der sicheren Architektur @heise_devSecMario-Leander Reimer
Sicherheit ist leider immer noch eine allzu häufig vernachlässigte nicht-funktionale Eigenschaft heutiger IT-Systeme. Auftraggeber haben oft nur die implizite Erwartung an ein sicheres System. Wir als Entwickler konzipieren und bauen aber genau das, was explizit gefordert wurde. Mit manchmal unangenehmen Konsequenzen.
Das Nachrüsten von Sicherheit in ein bestehendes System ist arbeitsintensiv, zeitaufwändig und teuer. Einfacher ist es, die Sicherheit bereits vom ersten Tag an mit zu berücksichtigen. Hört sich schwierig an? Das muss nicht sein.
Dieser Vortrag präsentiert einfache Regeln, Tools, Technologien und Entwurfsmuster für sichere Systemarchitekturen, die ein sicherheitsorientierter Entwickler oder Architekt definitiv kennen sollte. @heise_devSec @qaware #heisedevsec
Das kleine Einmaleins der sicheren ArchitekturQAware GmbH
//heise devSec() 2017, Heidelberg: Vortrag von Mario-Leander Reimer (@LeanderReimer, Cheftechnologe bei QAware) und Simon Bäumler (Softwarearchitekt bei QAware).
Abstract: Sicherheit ist leider immer noch eine allzu häufig vernachlässigte nicht-funktionale Eigenschaft heutiger IT-Systeme. Auftraggeber haben oft nur die implizite Erwartung an ein sicheres System. Wir als Entwickler konzipieren und bauen aber genau das, was explizit gefordert wurde. Mit manchmal unangenehmen Konsequenzen.
Das Nachrüsten von Sicherheit in ein bestehendes System ist arbeitsintensiv, zeitaufwändig und teuer. Einfacher ist es, die Sicherheit bereits vom ersten Tag an mit zu berücksichtigen. Hört sich schwierig an? Das muss nicht sein.
Dieser Vortrag präsentiert einfache Regeln, Tools, Technologien und Entwurfsmuster für sichere Systemarchitekturen, die ein sicherheitsorientierter Entwickler oder Architekt definitiv kennen sollte.
Im Rechenzentrum ist nicht nur ein einzelner Datenbankadministrator für die Verfügbarkeit der Daten verantwortlich. Der Vortrag von Senior Consultant Andreas Reinhardt (OPITZ CONSULTING) zeigt Faktoren, die zur Vermeidung von Datenverlust und zur schnellstmöglichen Datenwiederherstellung beitragen können. Betrachtet werden die Herausforderungen und die Kommunikation im Rechenzentrumsbetrieb sowie das technische Konzept zur Sicherung und Wiederherstellung der Daten.
Professionelle Anforderungsanalyse am Beispiel einer Java-Anwendung zur Betri...GFU Cyrus AG
Der Erfolg von Softwareentwicklungsprojekten hängt maßgeblich von einer guten Anforderungsanalyse ab. Je später Konzeptionsfehler erkannt werden, desto höher sind die Kosten der erforderlichen Korrekturen. Wir stellen in diesem Vortrag dar, wie durch eine strukturierte und dabei nicht zu formale Vorgehensweise frühzeitig sichergestellt werden kann, dass die später entwickelte Anwendung den Wünschen des Auftraggebers entspricht und zudem eine verlässliche Basis für die Einschätzung des Entwicklungsaufwands entsteht.
Im Vortrag verdeutlichen wir die Vorgehensweise an dem Beispiel einer Konzeption eines Systems zur Betriebsdatenerfassung und Leistungsentlohnung. Mit einem Mix aus Office- und UML-Werkzeugen konnte hier in kurzer Zeit ein gemeinsames Verständnis mit der Fachabteilung des Kunden erreicht werden und die formale Basis für die nachfolgende Realisierung des Systems geschaffen werden.
Auswahl von Werkzeugen aus dem Office- und Modellierungsumfeld
Halbformale Beschreibung von Anwendungsfällen
Erstellung eines fachlichen und technischen Glossars
Komponentenmodellierung mit UML
Entwicklung eines Anwendungs-Prototyps
Dataservices - Data Processing mit MicroservicesQAware GmbH
IT-Tage 2018, Frankfurt: Vortrag von Mario-Leander Reimer (@LeanderReimer, Cheftechnologe bei QAware)
=== Dokument bitte herunterladen für bessere Lesbarkeit! ===
Abstract: Data Processing und Microservices sind ein perfektes Gespann. In dieser Kombination können Microservices dazu verwendet werden, ein flexibles, Event-getriebenes und skalierbares System von lose gekoppelten Datenverarbeitungsaufgaben aufzubauen. Diesen Ansatz nennen wir Dataservices.
In diesem Vortrag stellen wir zunächst die wesentlichen Konzepte und einige Schlüsseltechnologien vor, um Dataservice-Architekturen zu realisieren. Anschließend werden wir die einzelnen Bestandteile einer exemplarischen Datenverarbeitungs-Pipeline schrittweise komponieren und die Showcase-Pipeline in der Cloud zur Ausführung bringen und skalieren.
Apache DeviceMap - Mobile Geräteerkennung für Java EE - JavaLand 2014Werner Keil
Das Wachstum an Mobiltelefonen, Tablets und ähnlichen Geräten, die den Markt geradezu überschwemmen erleben wir Tag für Tag.
Die Spezifikation jedes Einzelnen genau zu verfolgen ist ein Knochenjob. Diese Mühe kann reduziert werden, wenn zur Verbesserung dasDevice Description Repository – kurz DDR - beigesteuert wird und Anwender dieses selbst verwaltet können.
Apache DeviceMap enstand als Kooperation von Adobe, OpenDDR und anderen, um ein umfassendes Open Source Daten-Repository mit Geräteinformationen, Bilder und andere relevante Informationen für alle Arten von mobilen Geräten zu schaffen, Smartphones, Tablets, Smart-TV, u.dgl.
Das Projekt begann im Januar 2012, im Herbst 2012 wurden DDR APis für Java und .NET von OpenDDR beigesteuert. Die nächsten Schritte sind ein gemeinschaftliches Device Repository, eine Speicher-Struktur, die langfristige Erhaltung und Pflege dieser Daten durch die Apache Gemeinde erlaubt, unter Nutzung geläufiger Formate, wahrscheinlich JSON und / oder XML.
Slides zu meinem Talk beim Entwicklertag 2015 in Karlsruhe.
# Zusammenfassung
Sicherheit von Web-Anwendungen ist ein heißes Thema. Obwohl seit Jahren aktuell, werden die Meldungen über erneute Lücken gefühlt eher schlimmer als besser. Der Trend zu Single-Page-Anwendungen bringt für uns Entwickler eine ganze Reihe neuer Herausforderungen in punkto Sicherheit mit sich, da immer mehr Funktionalität in den Browser verlagert wird und dadurch mehr Code in nicht vertrauenswürdiger Umgebung läuft.
In diesem Talk wir anhand von AngularJS gezeigt auf was man bei SPAs achten muss. Anhand von Code-Beispielen wird natürlich auch gezeigt wie man sich z.B. vor Cross-Site-Scripting, Cross-Site-Request-Forgery und Code-Injection schützt und welche Gefahren sonst noch so lauern.
# Kurz-Bio
Philipp Burgmer studierte an der Hochschule Karlsruhe Informatik und arbeitet als Entwickler, Berater und [Trainer](http://thecodecampus.de) für die [w11k GmbH](http://w11k.de). Er ist Experte für Webtechnologien und beschäftigt sich mit der Gestaltung und Optimierung von Benutzeroberflächen. Privat interessiert er sich für Klettern und DJing.
The pain of choice - Important libs for C# developers
Vermeidung von Stille und Rauschen in API-Dokumentatio
1. Vermeidung von Stille und Rauschen in
API-Dokumentation
Vortrag auf dem 250. Treffen der GI- / ACM- Regionalgruppe HH
Jan Christian Krause (AKRA GmbH)
2. Jan Christian Krause 224.06.11
Agenda
1) Motivation
2) Metaphern „Stille“ und „Rauschen“
3) State of the Art der API-Dokumentation
4) Dokumentation mit thematischen Rastern
5) Open Source Werkzeug „iDocIt!“
6) Fallbeispiel: Ebay Trading API
7) Zusammenfassung und Ausblick
Ziele dieses Vortrags:
Lücken in Doku-Ansätzen aufzeigen
Neues Doku-Verfahren vorstellen
Werkzeug iDocIt! demonstrieren
Keine Ziele dieses Vortrags:
Detailbetrachtung von Doku-Tools
Det. Überblick über Doku-Ansätze
3. Jan Christian Krause 324.06.11
?
Motivation (I)
„Der Code ist die Dokumentation!“
„Working Software over
comprehensive documentation*.“
Quelltext-Dokumentation wird häufig stiefmütterlich gehandhabt
Eigene Beobachtung: Bedarf an „guter“ Dokumentation existiert
* Entnommen aus dem Agile Manifesto (verfügbar unter http://agilemanifesto.org/)
4. Jan Christian Krause 424.06.11
Motivation (II)
1)Welche Einflüsse determinieren den Zeitaufwand zur Quelltext -
Kommentierung?
2)Können diese Einflüsse durch Einsatz geeigneter Werkzeuge
kompensiert werden?
Übergeordnete Fragestellungen:
5. Jan Christian Krause 524.06.11
Metaphern „Stille“ und „Rauschen“
* Übertragen aus: Bertrand Meyer: „On Formalism in Specifications“, Vol. 3, no. 1. IEEE Software, 1985
Stille:
Relevanter Aspekt der Operation, der in der Dokumentation nicht
erwähnt wird
Rauschen:
Redundante, nicht aktuelle oder unnötig ausführliche Dokumentation zu
einem Aspekt der Operation
Definitionen:
6. Jan Christian Krause 624.06.11
State of the Art d. API-Doku. (I)
„[...] Rather, the architect should expose only what users of an element
[an API] need to know in order to interact [or communicate] with it. [...]“
Was sollte dokumentiert werden?
[Clements et al., 2002], p. 226
„[...] Write down only those effects that are visible to a user [...]“
[Clements et al., 2002], p. 230
Quelle:
P. Clements, F. Bachmann, L. Bass, D. Garlan, J. Ivers, R. Little et al., Documenting Software Architectures – Views and
Beyond, Addison-Wesley Professional, 2002
7. Jan Christian Krause 724.06.11
State of the Art d. API-Doku. (II)
●
Vorgabe eines Rasters, welches auszufüllen ist (z.B. Javadoc oder WSDL)
●
Inhalte des Rasters sind öffentliche Signaturelemente einer Operation (z.B.
Parameter, etc.), sowie Metadaten (z.B. Autor, etc.)
●
Natürlichsprachliche Kurzbeschreibung dessen, was die Operation macht
●
Vor- und Nachbedingungen (meiner Erfahrung eher selten)
●
...
Dokumentation in der Praxis:
8. Jan Christian Krause 824.06.11
State of the Art d. API-Doku. (III)
Seiteneffekte?
Vollständigkeit natürlichsprachlicher Beschreibungen?
Spezifikationen (z.B. einer Rechenvorschrift)?
Leser-Zielgruppen?
Nicht sichtbare Parameter (z.B. in Konfigurationsdateien)?
...
Weitgehend standardisiertes und etabliertes Vorgehensmodell
Breite Werkzeugpalette verfügbar
Zusammenfassung:
Gefahr von
Stille
9. Jan Christian Krause 924.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstellenelement Dokumentation
Schnittstelle: CustomerCareService Provides eletronical services of the customer
care department.
Operation: findCustomerById Returns the customer-record with the given
id. If no record is found, the result will be
NULL.
Parameter:
Integer customerId The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Rückgabetyp: Customer The customer-record with the given id.
10. Jan Christian Krause 1024.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstellenelement Dokumentation
Schnittstelle: CustomerCareService Provides eletronical services of the customer
care department.
Operation: findCustomerById Returns the customer-record with the given
id. If no record is found, the result will be
NULL.
Parameter:
Integer customerId The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Rückgabetyp: Customer The customer-record with the given id.
Redundanz (Rauschen der Kategorie 1)
11. Jan Christian Krause 1124.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstellenelement Dokumentation
Schnittstelle: CustomerCareService Provides eletronical services of the customer
care department.
Operation: findCustomerById Returns the customer-record with the given
id. If no record is found, the result will be
NULL.
Parameter:
Integer customerId The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Rückgabetyp: Customer The customer-record with the given id.
Redundanz (Rauschen der Kategorie 1) Nicht problemrelevant
(Rauschen der Kategorie 2)
12. Jan Christian Krause 1224.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstellenelement Dokumentation
Schnittstelle: CustomerCareService Provides eletronical services of the customer
care department.
Operation: findCustomerById Returns the customer-record with the given
id. If no record is found, the result will be
NULL.
Parameter:
Integer customerId The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Rückgabetyp: Customer The customer-record with the given id.
Redundanz (Rauschen der Kategorie 1) Nicht problemrelevant
(Rauschen der Kategorie 2)
Gefahr von
Rauschen
Veraltete Angaben (Rauschen der Kategorie 3)
13. Jan Christian Krause 1324.06.11
Dokumentation mit them. Rastern (I)
●
Beobachtung: Operationsbezeichner enthalten meist ein Verb
●
Ein Verb hat eine Bedeutung, die durch zusätzliche Argumente (thematische
Rollen) weiter spezifiziert werden kann
●
Die Zuordnung von möglichen Argumenten zu einem Verb erfolgt über ein
thematisches Raster
Grundkonzept:
14. Jan Christian Krause 1424.06.11
Dokumentation mit them. Rastern (II)
Beispiel: them. Raster für to find
Name: Searching Operations
Description: Represents operations which fetch one or more objects from a defined
source. The returned objects are identified by a specified set of criteria.
Verbs: find, get, search, look
Mandatory Roles: OBJECT, COMPARISON, SOURCE
Optional Roles: ORDERING, ALGORITHM
15. Jan Christian Krause 1524.06.11
Dokumentation mit them. Rastern (III)
Beispiel - Vermeidung von Stille:
Find
[OBJECT] [COMPARISON] [SOURCE]
Find
[OBJECT Customer] [COMPARISON customerId] [SOURCE ???]
16. Jan Christian Krause 1624.06.11
Dokumentation mit them. Rastern (IV)
Beispiel - Vermeidung von Rauschen:
Parameter Dokumentation
customerId The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Parameter Them. Rolle Dokumentation
customerId PRIMARY KEY The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
1. Thematische Rolle zuordnen
17. Jan Christian Krause 1724.06.11
Dokumentation mit them. Rastern (IV)
Parameter Them. Rolle Dokumentation
customerId PRIMARY KEY The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Parameter Them. Rolle Dokumentation
customerId PRIMARY KEY The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
2. Rauschen erkennen
Beispiel - Vermeidung von Rauschen:
18. Jan Christian Krause 1824.06.11
Dokumentation mit them. Rastern (IV)
Parameter Them. Rolle Dokumentation
customerId PRIMARY KEY The id of the customer to look for. Only
values greater or equal to zero are valid.
NULL is not permitted here. You can pass
NULL only as parameter to the
createCustomer-operation of this interface.
Beispiel - Vermeidung von Rauschen:
3. Rauschen entfernen
Parameter Them. Rolle Dokumentation
customerId PRIMARY KEY NULL is not permitted here.
19. Jan Christian Krause 1924.06.11
Dokumentation mit them. Rastern (V)
Zusammenfassung:
Stille und Rauschen kann mit Hilfe thematischer Raster vermieden werden
Them. Raster helfen ebenfalls bei der Definition von Operationen einer
Schnittstelle (z.B. bei der Bestimmung der Parameter)
Them. Raster funktionieren ohne Kenntnis von Quelltexten
Kardinalitäten thematischer Rollen nicht ableitbar (z.B. Anzahl SOURCEs)
Qualität der Bezeichner determiniert Qualität der Unterstützung
Them. Raster müssen definiert werden
iDocIt! Bietet 19 Default-Raster
20. Jan Christian Krause 2024.06.11
Open Source Werkzeug „iDocIt“
●
Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoff (AKRA GmbH)
●
Eclipse Plugin (Helios 3.6)
●
Open Source-Projekt bei Google Code (http://code.google.com/p/idocit/)
●
Unterstützt derzeit WSDL und Java
●
Erstes Release: 01.07.11 (geplant)
Kurzbeschreibung:
●
Editor zur Dokumentation mit them. Rollen und Rastern
●
Anzeige passender them. Raster pro Operation
●
HTML-Export der Dokumentation
●
Erweiterbar um weitere Programmier- / Markupsprachen (als Plugins)
Features:
21. Jan Christian Krause 2124.06.11
Fallbeispiel: Ebay Trading API (I)
Überblick:
●
Ebay bietet Web Service zur Integration von Ebay-Diensten in Anwendungen
●
Analysiert wird die Operation getFeedback(...)
●
Ziel: Ermittlung von Stille und Rauschen
●
Nutzung von iDocIt! als Analyse-Werkzeug
22. Jan Christian Krause 2224.06.11
Fallbeispiel: Ebay Trading API (II)
Ergebnisse - Stille:
●
Sortierung der zurückgelieferten Bewertungen ist nicht spezifiziert [them.
Rolle ORDERING]
●
Unterschiedliche Datenquellen (Sandbox- und Produktivumgebung) sind
nur unzureichend dargestellt [them. Rolle SOURCE]
●
Berechnungsvorschrift für die Feedback-Punktzahl ist nicht dokumentiert
(findet sich an anderer Stelle in der Ebay Online-Hilfe) [them. Rolle
FORMULA]
23. Jan Christian Krause 2324.06.11
Fallbeispiel: Ebay Trading API (III)
●
Vermeidung von Redundanz durch Nutzung der Rolle PRIMARY KEY für ID-
Felder (z.B. FeedbackID)
●
Durch Anwendung des Lokalitätsprinzips bzgl. Felddokumentation lässt sich
viel Rauschen der Kategorie 2 einsparen, z.B. bei Feld DetailLevel.
Ergebnisse - Rauschen:
24. Jan Christian Krause 2424.06.11
Zusammenfassung und Ausblick
●
Thematische Raster können helfen Stille und Rauschen zu vermeiden
●
Voraussetzung sind präzise gewählte Verben in den Operationsbezeichnern
●
Kardinalitäten thematischer Rollen sind nicht ableitbar
●
AKRA sammelt Erfahrungen mit diesem Verfahren in mehreren Projekten
●
Offen bleibt: wie viel Dokumentation schafft wirklichen Mehrwert?
Zusammenfassung:
Ausblick:
●
Weiterentwicklung von iDocIt! (Usability, Stabilität, etc.)
●
Definition domänenspezifischer thematischer Raster
●
Nutzung der Erkenntnisse im Bereich der Workflow-Modellierung
●
Dokumentation von Klassenmodellen mithilfe them. Rollen
25. Jan Christian Krause 2524.06.11
Diskussion
Vielen Dank für Ihre Aufmerksamkeit.
Haben Sie Fragen, Anregungen oder
Kritik?