Schnitt­stellen­beschrei­bungen sind alter­nativ­los in einer kom­plexen IT-System­land­schaft mit vielen unab­hängi­gen Par­tner­systemen aus ver­schiede­nen Organi­sationen eines Unter­nehmens. Ein Pro­dukt­verant­wort­licher darf sich trotz­dem die Frage stel­len, wie umfang­reich so ein Doku­ment sein muss. Mit cards+ ist es mög­lich, eine Schnitt­stellen­beschrei­bung aus einem Rahmen­doku­ment — die Start­seite der Schnitt­stelle — und den Bau­steinen der System­beschrei­bung und System­struk­tur zusam­men­zu­stel­len. Neben der Start­seite muss der Pro­dukt­verant­wort­liche nur eine weitere Seite je ange­schlos­senem IT-System im Wiki anle­gen.

Eine Start­seite für jede Schnittstelle legt mit ihrem Seiten­titel eine ein­deutige Kennung für die Schnitt­stelle fest, auf die auch in anderen Doku­men­ten referen­ziert werden kann. Sie ist prak­tisch eine Link­samm­lung für alle Bau­steine, die rele­vant für die Schnitt­stelle sind. Die Rele­vanz wird eben­falls durch die Kennung der Schnitt­stelle als Stich­wort in den betroffe­nen Seiten aus­gedrückt. Die Start­seite hat fol­gen­den grund­sätz­lichen Auf­bau:

• Im Abschnitt Referen­zen werden alle ange­schlos­senen IT-Systeme gelistet.
• Der Abschnitt System­kontext zeigt die End­punkte (Baustein Service) der beteilig­ten IT-Systeme in einem schema­tischen Kompo­nenten­über­blick.
• Im Abschnitt Operatio­nen wird jede ein­zelne Operation der Schnitt­stelle beschrie­ben. Neben einer kur­zen Beschrei­bung der Operation gibt es hier Infor­matio­nen zur Häufig­keit der Auf­rufe, zu den Para­metern und Rück­gabe­wer­ten und Beson­der­hei­ten der Feh­ler­behand­lung.
• Der Abschnitt Beschrei­bung ver­knüpft in einer Tabelle jede Operation mit den Fähig­keiten der Soft­ware (Baustein Case) und einem Aus­löser (Baustein Event) — falls es einen gibt.
• Der Abschnitt Versio­nierung legt eine ver­bind­liche Stra­tegie für die Evo­lution der Schnitt­stelle fest, mit einer Ver­knüpfung zum ent­sprechen­den Kon­zept (Baustein Concept).
• Der Abschnitt Quali­täts­merk­male legt ver­bindl­iche Vor­gaben für den Betrieb der Schnitt­stelle fest, mit Ver­knüpfun­gen zu ent­sprechen­den Kon­zep­ten (Baustein Concept) und Ent­schei­dungen (Baustein Decision)

Der Pro­dukt­verant­wort­liche erreicht durch dieses Vor­gehen ein hohes Maß an Wieder­ver­wen­dung bereits exis­tieren­der doku­men­tier­ter Infor­matio­nen im Wiki.

• Der End­punkt der Schnitt­stelle aus der Per­spek­tive des bereit­stellen­den IT-Systems wird mit dem Bau­stein Service in der System­struk­tur doku­men­tiert. Die Spezifi­kation beant­wor­tet alle Fra­gen zur Imple­mentie­rung.
• Der End­punkt der Schnitt­stelle aus der Per­spek­tive jedes ange­schlos­sene IT-Systems wird mit dem Bau­stein Service als Unter­seite der Start­seite der Schnitt­stelle doku­men­tiert. Die Spezifi­kation beschreibt das Ver­halten des Partner­systems bezo­gen auf die Schnitt­stelle, so wie es verein­bart wurde.
• Mit dem Bau­stein Event werden Nach­rich­ten­objekte einer event-basier­ten Schnitt­stelle doku­men­tiert.
• Mit dem Bau­stein Entity werden Infor­mations­objekte einer batch-orien­tier­ten Schnitt­stelle doku­men­tiert.
• Der Bau­stein Case gibt Ein­blick in die Fähig­keiten der Schnitt­stelle.

Dieses Vor­gehen ver­schafft den Ent­wick­ler der Pro­jekt­organi­sation des Par­tner­systems einen sehr tief­gehen­den Ein­blick in die Reali­sie­rung der Schnitt­stelle. Das för­dert das Ver­ständnis von Daten­struk­turen und beugt Fehlern in der Ver­wendung der Operationen vor. Die hohe Transpa­renz erhöht außer­dem die Chan­cen, dass die «fremden» Ent­wick­ler konstruk­tives Fee­back geben. Das ist ein nicht zu unter­schätzen­der Vor­teil, um Fehler in der Schnitt­stelle früh­zeitig zu identi­fizie­ren.

In vielen Fällen hat die Pro­jekt­organi­sation der Partner­systeme kei­nen Zugriff auf das Wiki oder es gibt eine Vor­gabe des Unter­nehmens, jede Schnitt­stellen­beschrei­bung revi­sions­sicher in einem Doku­menten­manage­ment­system abzu­legen. Dazu wird die Start­seite der Schnitt­stelle mit allen ver­knüpf­ten Bau­steinen aus dem Wiki expor­tiert. Beim Export aus dem Wiki sorgt die Ein­schrän­kung auf die Kennung der Schnitt­stelle, dass nur die für das Partner­system inter­essan­ten Seiten expor­tiert werden. Als For­mat bie­ten sich Word oder PDF an. In beiden Forma­ten blei­ben die Ver­knüpfun­gen inner­halb des expor­tier­ten Doku­mentes erhal­ten.