Sie haben eine großartige Software! Ihre Entwickler haben mehrere Jahre investiert, das GUI entspricht neuesten UX-Erkenntnissen und die Funktionen sind nicht nur vielfältig, sondern auch extrem clever.
Damit allein wird die Software aber leider noch nicht zum Kassenschlager. Möglichst viele Kunden müssen sie nun auch erfolgreich einsetzen. Zur Nutzbarkeit einer Software gehört zum einen natürlich eine intuitiv bedienbare Oberfläche, zum anderen aber auch die nahtlose Integration in die bestehende Systemlandschaft. Während für die Bedienung der Oberfläche maximal ein integriertes Tutorial nötig sein sollte, kommt spätestens bei der Integration in die Systemlandschaft auch in der schönen neuen Welt die gute alte Doku zum Tragen. Und zwar in Gestalt einer Schnittstellen-Dokumentation.
Eine gute Schnittstellen-Dokumentation bringt einen ganzen Strauß an Chancen mit sich: Je leichter die Parameter einer Software zugänglich sind, desto attraktiver ist es, sie direkt in eine andere Software einzubinden, z. B. ein Übersetzungstool direkt in das Redaktionsprogramm. Das ist nicht nur ungemein praktisch, sondern auch ein echter Wettbewerbsvorteil.
Je leichter eine Software zugänglich ist, desto attraktiver ist es zudem für andere Entwickler, zusätzliche Programme darauf aufzubauen. Ein vielfältiges Angebot an Add-ons steigert wiederum die Attraktivität der Ursprungssoftware.
An allen Stellen Schnittstellen
Programmierschnittstellen sind kein hübsches Zusatzfeature, sondern eine zentrale Komponente vieler Anwendungen.
Nehmen wir an, Sie sind Maschinenbauer. Für die Maschinensteuerung haben Sie einen Webservice zur Verfügung gestellt, der nicht nur den Maschinenführern die Steuerung vom Rechner aus ermöglicht, sondern auch Technikern von anderen Standorten aus spontan Zugriff auf die Maschine gewähren kann. Die gelungene Kommunikation zwischen Maschine und Webservice ist nur durch eine Schnittstelle möglich.
Nehmen wir an, Sie entwickeln verschiedene Überwachungstools für z. B. Temperatur, Windstärke oder Niederschlagsmenge. Diese Tools können für das SCADA-Systems eines Windparks Gold wert sein. Vorausgesetzt, sie lassen sich über Schnittstellen gut in das SCADA-System einbinden.
Nehmen wir zu guter Letzt als Königsdisziplin den Logistikprozess eines Versandhändlers: Lagerverwaltung, Produktdatenbank, Bestelloberfläche, Buchungssoftware – alles muss nahtlos ineinandergreifen. Sie können versuchen, alle Softwarekomponenten vom gleichen Hersteller zu kaufen. Das muss aber für die Einzeltools nicht immer die beste Lösung sein. Besser wäre es, aus allem das für Sie Optimale zu wählen und über Schnittstellen zu verbinden.
Anforderungen an die API-Dokumentation
Egal wie eine solche Schnittstelle realisiert ist, ob als REST API, Protokoll oder dateiorientiert, die Nutzbarkeit steht und fällt mit der Zugänglichkeit der Funktionen. Dokumentiert werden diese in speziellen Spezifikationsformaten und Frameworks, damit sie für Mensch und Maschine lesbar sind.
Die zentralen Ziele einer Schnittstellen-Dokumentation sind die folgenden:
- Die Funktion der Anwendung erläutern.
- Die Parameter erläutern, mit denen die Schnittstelle arbeitet.
- Die technischen Voraussetzungen zum Betrieb der Schnittstelle nennen.
- Die in der Anwendung verwendeten Objekte und ihre Hierarchie aufführen.
- Anwendungsbeispiele geben.
- Programmierrelevante Angaben machen, z. B. zu Abhängigkeiten zwischen Objekten und Funktionen.
- Erläuterungen zu verwendeten Konzepten und der Programmierphilosophie geben, um das "Reinlesen" in den Code zu erleichtern.
Damit Softwareprodukte aus einem Haus auch eine gemeinsame Philosophie verfolgen, verwenden viele Softwarehäuser Styleguides, z. B. auch für die Erstellung von Schnittstellen. Guten Programmierstil zeichnet Einheitlichkeit in Philosophie und Konzept aus. Wie bei allen Produkten gilt auch bei Schnittstellen: Habe ich das erste Produkt eines Herstellers verstanden und für gut befunden, steigt die Wahrscheinlichkeit, dass ich mit dem nächsten von vornherein schneller zurechtkomme und der Marke treu bleibe.
Der Entwickler oder die Entwicklerin ist jedoch bei der Dokumentation nicht unbedingt in die Pflicht zu nehmen. Bekanntermaßen sind Muttersprachler nicht unbedingt die besten Grammatiklehrer.
