28.07.2021
in EcoSystem
Cloudogu EcoSystem Dokumentation (docs)
Inhaltsverzeichnis
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 auf den ersten Blick sehr einfach aus, obwohl es umfangreiche Operationen unter der Oberfläche verbirgt. Deswegen stellt das Cloudogu EcoSystem 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?
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 Cloudogu-Platform-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.
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 Cloudogu EcoSystem 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.
Cloudogu EcoSystem
Überzeugen Sie sich von den Vorteilen des Cloudogu Ecosystem. Nutzen Sie jetzt kostenlos die moderne DevOps Plattform.
Zur Plattform
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.
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 Cloudogu-Platform-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.
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.
Jetzt Newsletter abonnieren
Verpassen Sie nicht die neusten Informationen zur Digitalen Transformation, Ankündigungen von Produktneuheiten und Sonderaktionen.
Aktuelle Diskussion
Kommentare zu diesem Thema auf der Cloudogu Platform
