Ankommen am Bahnhof: Die Entwicklung unserer API-Dokumentationsplattform

Vor drei Jahren wurde unsere Dokumentationsplattform ins Leben gerufen. Wir wussten nicht, welche Auswirkungen einige der damals getroffenen Designentscheidungen heute haben würden. So entschieden wir uns beispielsweise für eine Open-Source-Webanwendung mit Ruby on Rails anstelle von statischen Website-Generatoren für Markdown-Dateien, z. B. Jekyll, Middleman usw.

Die bisherige Geschichte

Ein Web-Framework wie Rails war die perfekte Wahl, weil es keine Annahmen darüber macht, was damit gebaut werden soll, was Ihnen die Flexibilität gibt, zu allem Ja zu sagen.

Vor drei Jahren wussten wir nicht, welchen Umfang unser Projekt als schnelllebiges API-Unternehmen letztendlich haben würde. Es ist schwer, sich vorzustellen, wie weit unsere Dokumentationsplattform gewachsen ist, und es ist noch schwerer, sich vorzustellen, was sie in Zukunft werden könnte.

In der Gegenwart hat sich das Tooling rund um die Plattform erheblich erweitert. Von der automatischen Rechtschreibprüfung über die Internationalisierung bis hin zur Überprüfung der API-Spezifikationen auf Gültigkeit und Stil, und die Liste wird immer länger.

Seit ihrer Gründung hat die Plattform die Vonage API-Entwickler. Vonage API Developer begann als Nexmo Developer und hat sich in den Jahren seit seiner Gründung zu einem Teil von Vonage, dem weltweit führenden Anbieter von Unified Cloud Communications, entwickelt. Infolgedessen sind die Anforderungen und Erwartungen an die Plattform scheinbar exponentiell gewachsen.

Damit war die Geschichte der Entwicklung der Plattform noch nicht zu Ende.

Die Geschichte geht weiter...

Vor sechs Monaten wandte sich ein anderes Produktteam in unserem Unternehmen an uns, weil das Tool, das sie für ihre Dokumentations-Website verwendeten, das Ende seiner Lebensdauer erreicht hatte. Sie waren begeistert von der Umstellung auf eine einfache Kopie der Vonage API Developer-Plattform, aber leider war diese nicht einsatzbereit. Nicht nur, dass sich der Code der Plattform und die Dokumentation von Vonage API Developer im selben Repository befanden, sondern auch, dass einige der Seiten und Funktionen nicht für die Unterstützung anderer Modalitäten von Inhalten ausgelegt waren, die für diese Produktlinie einzigartig waren.

Die zunehmende Komplexität der Tooling-Anforderungen, die einer einzelnen monolithischen Rails-Anwendung auferlegt werden, in Verbindung mit einem zunehmenden Interesse an der Nutzung der Plattform durch verschiedene Produktlinien bei Vonage, veranlasste uns, nach einer besseren Alternative zu suchen.

Durch diese Suche gelangten wir zur Station.

Was ist ein Bahnhof?

In den letzten Monaten haben wir die Prosa vom Code der Plattform getrennt. Wir haben sie zu einer inhaltsunabhängigen Plattform umgestaltet, die eine Vielzahl von Inhaltsformen und Medien unterstützt und andere Teams im gesamten Unternehmen befähigt.

Station ist ein Plattformwerkzeug. Durch das Definieren einiger Konfigurationsdateien und das Festlegen des Pfads, in dem sich Ihre Inhalte befinden, kann eine Website mit einem Befehl vom Terminal aus eingerichtet werden.

Es ist so konzipiert, dass es ohne weiteres die folgenden Funktionen bietet:

• Eine Lösung für die schnelle Erstellung von Websites mit textbasierten Inhalten

• Die Möglichkeit für jeden, unabhängig von seinen Programmierkenntnissen, Inhalte auf rationale Art und Weise beizutragen

• Hochgradig anpassbar an die Bedürfnisse der einzelnen Standorte durch eine Reihe von Konfigurationsdateien

Im Kern ist Station eine hochgradig maßgeschneiderte Ruby on Rails- (und Webpack-) Anwendung, die in einem Ruby Gem gebündelt ist - einem wiederverwendbaren Softwarepaket in der Programmiersprache Ruby. Für den erfahrenen Rails-Entwickler wird es sich vertraut anfühlen. Für Personen, die mit Rails nicht vertraut sind, ist es unnötig, die Feinheiten des Frameworks zu erlernen, um eine von Station betriebene Website zu betreiben oder Inhalte zu ihr beizutragen.

Was macht die Station?

Eine Station-Installation unterstützt von Anfang an die meisten Dinge, die man von einer Content-Site erwarten würde: Rendering von medienreichen Inhalten und OpenAPI-Spezifikationsdateien, schrittweise Anleitungen, benutzerdefinierte Webseiten, Anwendungsfälle, die Möglichkeit, Feedback zu geben, die Suche nach Inhalten, und die Liste geht weiter.

Nicht nur der Inhalt, sondern auch die meisten Teile der Website können mit Konfigurationsdateien angepasst werden. Das folgende Snippet entspricht der Konfigurationsdatei für die Kopf- und Fußzeile der Website.

So werden sie dann auf der Seite dargestellt.

Was kommt als Nächstes?

Wir sind zwar froh, dass wir eine robuste Plattform entwickelt haben, die jede Inhaltsseite unterstützt und derzeit die Dokumentationsseite von zwei unserer Teams antreibt, aber sie ist immer noch nicht vollständig für jedermann verfügbar.

Obwohl es Open-Source ist, wird der Edelstein über die Paketregistrierung von Github veröffentlicht, und die Versionen sind noch nicht für die Öffentlichkeit zugänglich. Wir planen jedoch, in Kürze eine öffentliche Version 1.0 zu veröffentlichen, die für jeden über Rubygems verfügbar sein wird.

In den nächsten Beiträgen werden wir über einige der oben erwähnten Tools sprechen, die wir entwickelt haben, um unsere Dokumentation und die Open-API-Spezifikationen auf höchstem Niveau zu halten.