Cloudogu Logo

Hallo, wir sind Cloudogu!

Experten für Software-Lifecycle-Management und Prozess­auto­mati­sierung, Förderer von Open-Source-Soft­ware und Entwickler des Cloudogu EcoSystem.

featured image Cloudogu EcoSystem Dokumentation (docs)
28.07.2021 in EcoSystem

Cloudogu EcoSystem Dokumentation (docs)

Vorstellung der Cloudogu Ecosystem docs

Das Prinzip guter Software ist, möglichst viele komplexe Zusammenhänge für den Nutzer verständlich darzustellen. So sieht das Cloudogu EcoSystem (CES) auf den ersten Blick sehr einfach aus, obwohl es umfangreiche Operationen unter der Oberfläche verbirgt. Deswegen stellt das CES auch überraschend viele Benutzeroberflächen zur Verfügung. Wir beachten Konventionen der Benutzerfreundlichkeit nach bestem Wissen und Gewissen, dennoch ist manche Funktion erklärungsbedürftig. Daher entschieden wir uns, eine umfassende, öffentliche Dokumentation und Anleitung als docs.cloudogu.com aufzubauen.

Was ist docs.cloudogu.com?

Dokumentationsplattform für das Cloudogu EcoSystem Abbildung 1: Dokumentationsplattform für das Cloudogu EcoSystem

Docs.cloudogu.com bietet Ihnen unterschiedlichste Informationen rund um das Cloudogu EcoSystem:

  • Ein Getting Started für neue Nutzer oder an der Plattform interessierte.
  • Ein Benutzerhandbuch für User der Plattform.
  • Eine Entwicklungsdokumentation für Administrierende und alle die selber Anpassungen an der Plattform machen möchten.

Die Dokumentation ist ein Bestandteil der myCloudogu-Services und ist ohne Registrierung sowie kostenfrei auf docs.cloudogu.com zu erreichen.

Was bietet mir docs.cloudogu.com?

Die Dokumentation richtet sich besonders an Endanwender:innen, Entwickler:innen und Administrator:innen sowie alle Personen, die sich für das Cloudogu EcoSystem interessieren.

Benutzerhandbuch

Unser EcoSystem ist eine Plattform die unterschiedlichste Software-Applikationen zu einer leistungsfähigen Toolchain verbindet. In dem Benutzerhandbuch finden Sie detaillierte Informationen für die Benutzeroberflächen unserer selbst entwickelten Werkzeuge wie dem Cockpit oder dem Warp Menü und erhalten Hinweise zur Nutzung. Sie erfahren, welche Optionen für Sie zur Verfügung stehen und wie Sie damit erfolgreich interagieren.

Entwicklerdokumentation

Sie administrieren eine Instanz des Cloudogu EcoSystems, wollen sich an der Entwicklung der Open-Source-Komponenten beteiligen oder einen tieferen Einblick in die technischen Zusammenhänge gewinnen? Dann beantwortet die Entwickler-Dokumentation Ihre Fragen zu Kommandozeilen-Optionen, Schnittstellen und Entscheidungen unserer Entwickler.

Details zu Komponenten (Dogus) des Cloudogu EcoSystem in der Entwicklerdokumentation Abbildung 2: Details zu Komponenten (Dogus) des Cloudogu EcoSystem in der Entwicklerdokumentation

Getting Started

Das Cloudogu EcoSystem ist ein komplexes Produkt für die agile Software-Entwicklung. Wenn Sie besser verstehen wollen, was die einzelnen Komponenten für Sie bieten und wie sie dabei ineinander greifen, dann ist die Dokumentation Ihre Anlaufstelle für Detailfragen. Wenn Sie das CES selbst ausprobieren wollen, zeigt Ihnen der Bereich Getting Started Schritt für Schritt, wie Sie eine lokale Instanz aufsetzen.

Sie haben Fragen, die unsere Dokumentation noch nicht abdeckt? Dann stellen Sie diese gerne in unserem Community-Forum. Für die genauen Informationen zu den Benutzeroberflächen und Optionen von dogurisierten Open-Source-Tools, (z.B. Redmine, Jenkins oder Sonatype Nexus) besuchen Sie bitte die Webseiten der Hersteller.

Warum gibt es docs.cloudogu.com?

Einer unserer Entwicklungsgrundsätze bei Cloudogu ist, dass wir Dokumentation möglichst nah am Code ablegen. Das betrifft sowohl die Dokumentation des Codes als auch Hinweise zu Benutzeroberfläche, Nutzung und Administration. Weiterhin legen wir Wert darauf, möglichst wenige Inhalte doppelt zu pflegen um widersprüchliche Informationen zu verhindern. Das bedeutet, dass unsere Dokumentation über eine Vielzahl von Repositories auf GitHub und im SCM-Manager verteilt ist.

Es war daher teilweise umständlich, einen Überblick über das Gesamtkonstrukt zu gewinnen. Weiterhin ist die Dokumentation in Quellcode-Repositories für Nicht-Entwickler weniger zugänglich. Auch die Navigation in den Dokumentationen ist ausschließlich in den Repositories nicht optimal. Um die Nachteile unserer Arbeitsweise für unsere Kunden und Benutzer:innen auszugleichen, entschlossen wir uns, alle öffentliche Dokumentation an einem Ort leicht zugänglich zu machen. In dem Moment in dem wir diese Entscheidung trafen, ergab sich die Chance, eine umfassende Dokumentation für verschiedene Nutzeransprüche strukturiert auszuliefern. Durch die Single Source of Truth wird unsere öffentliche Dokumentation stets aktuell bleiben, wir müssen keine doppelten Inhalte händisch pflegen.

Informationen zur Entwicklung für das Cloudogu EcoSystem in der Entwicklerdokumentation Abbildung 3: Informationen zur Entwicklung für das Cloudogu EcoSystem in der Entwicklerdokumentation

Was ist technisch unter der Haube?

Docs.cloudogu.com ist eine gatsby-Seite, welche aufbereitete Inhalte unserer Dokumentation liefert. Gatsby ist ein Webseiten-Generator, der auf React basiert. Über eine gemeinsame Bibliothek bezieht das Web-Frontend Elemente des myCloudogu-Universums wie Styling und gemeinsam genutzte Grafiken. Das technische Herz unseres Dokumentations-Werkzeugs ist ein Skript, das auf Basis von git sparse checkout die Dokumentationsbestandteile aus den Repositories einsammelt. Jedes zu besuchende Repository wird über eine JSON-Datei definiert. Dabei kann das Skript als Quellen sowohl github.com als auch unserem internen SCM-Manager behandeln. Wir sammeln Markdown-Dateien und Bilddateien.

Sammeln von Informationen aus unterschiedlichen Quellen Abbildung 4: Sammeln von Informationen aus unterschiedlichen Quellen

Das gatsby-transformer-remark-Plugin erzeugt auf Basis der gesammelten Markdown-Dateien den HTML-Content. Dabei werden die Markdown-Dateien in maschinenlesbare „Markdown Abstract Syntax Trees“ (mdAST -Objekte) transformiert und weiter bearbeitet. Das gatsby-transformer-remark-Plugin akzeptiert weitere Plugins. Hier setzt unser selbst entwickeltes Transformer-Plugin an, welches die Dokumentation nach hinterlegten Regeln aufbereitet und z.B. überflüssige Footer entfernt. Weiterhin bereitet das Plugin relative Links, die im Quell-Repository funktionieren, so auf, dass diese auch in unserer Dokumentation funktionieren.

Weiterhin nutzen wir GraphQL, eine populäre API-Abfrage-Sprache, um z.B. Menüs und Inhaltsverzeichnisse automatisch zu generieren.

Die spannendste Herausforderung für unsere Entwickler war, eine Architektur zu schaffen, welche die Daten aus heterogenen Umgebungen erfolgreich einsammelt und gleichzeitig flexibel genug ist, um auf sich ändernde Anforderungen zu reagieren (Wir arbeiten nach den SCRUM-Prinzipien und passen Anforderungen permanent an neue Erkenntnisse an). Organisatorisch gab uns die Arbeit an der öffentlichen Dokumentation die Chance, alle vorhandene Dokumentation nach einem einheitlichen Standard aufzubereiten.

Wie geht es weiter?

So wie Software niemals „fertig“ ist, entwickeln wir unsere Dokumentation permanent weiter. Wir planen sowohl die Anzahl der Artikel wie auch die Tiefe zu erhöhen und Schritt für Schritt alle Themen rund um das Cloudogu EcoSystem zu behandeln. Weiterhin denken wir über eine Englische Version nach. Auch die Usability werden wir weiter verbessern. Bei all diesen Themen sind wir auf Ihre Mithilfe angewiesen. Nutzen Sie docs.cloudogu.com und sagen Sie uns im Forum, was Ihnen gefällt und wo wir besser werden können.


Philipp Ahrendt
Philipp Ahrendt

- UI-/UX-Experte -

Philipp arbeitet bei Cloudogu daran, Usern den Umgang mit Software ein Stück leichter zu machen. Er hat langjährige Erfahrung in verschiedenen Designdisziplinen. Dennoch ist er immer wieder erstaunt, auf welche kreative Arten Nutzer Produkte einsetzen.