Cloudogu EcoSystem documentation (docs)

---

---

Introducing docs for the Cloudogu Ecosystem

The principle of good software is to present as many complex relationships as possible in an easily understandable way. Thus, our Cloudogu EcoSystem looks pretty simple even though it hides extensive operations under the surface. Nevertheless, the Cloudogu EcoSystem provides a surprising number of user interfaces. Even though we observe usability conventions to the best of our ability, yet some functionality requires explanation. Therefore, we decided to build a comprehensive, public documentation and guide as docs.cloudogu.com.

What is docs.cloudogu.com?

Figure 1: Documentation platform for the Cloudogu EcoSystem

Docs.cloudogu.com provides a wide variety of information related to the Cloudogu EcoSystem:

• A Getting Started for new users or those interested in the platform.
• A user manual for users of the platform.
• A development documentation for administrators and all those who want to make adjustments to the platform themselves.

The documentation is part of the Cloudogu platform services and can be accessed without registration and free of charge at docs.cloudogu.com.

What does docs.cloudogu.com offer me?

The documentation is especially intended for end users, developers and administrators, as well as anyone interested in the Cloudogu EcoSystem.

User Manual

Our EcoSystem is a platform that connects different software applications to a powerful toolchain. In the user manual you will find detailed information for the user interfaces of our self-developed tools like the Cockpit or the Warp Menu and get hints on how to use them. You will learn which options are available to you and how to interact with them successfully.

Developer documentation

Do you administer an instance of the Cloudogu EcoSystem, want to participate in the development of the open source components or gain a deeper insight into the technical interrelationships? Then the developer documentation answers your questions about command line options, interfaces and decisions of our developers.

Figure 2: Details on components (Dogus) of the Cloudogu EcoSystem in the developer documentation

Getting Started

The Cloudogu EcoSystem is a complex product for agile software development. If you want to better understand what each component offers you and how they interact in the process, the documentation is your go-to resource for detailed questions. If you want to try out the Cloudogu EcoSystem yourself, the Getting Started section shows you step-by-step how to set up a local instance.

Do you have questions that our documentation does not yet cover? Then feel free to ask them in our community forum. For detailed information on the user interfaces and options of dogurized open-source tools, (e.g. Redmine, Jenkins or Sonatype Nexus) please visit the manufacturers’ websites.

Why does docs.cloudogu.com exist?

One of our development principles at Cloudogu is to put documentation as close to the code as possible. This includes documentation of the code as well as notes on user interface, usage and administration. Furthermore, we make it a point to maintain as little content twice as possible to prevent conflicting information. This means that our documentation is spread out across a number of repositories on GitHub and in SCM-Manager.

It was therefore sometimes cumbersome to gain an overview of the overall construct. Further, documentation in source code repositories is less accessible to non-developers. Also, navigating the documentation exclusively in the repositories is not optimal. To compensate for the disadvantages of our way of working for our customers and users, we decided to make all public documentation easily accessible in one place. The moment we made this decision, the opportunity arose to deliver comprehensive documentation for different user needs in a structured way. With the single source of truth, our public documentation will always be up-to-date, we will not have to manually maintain duplicate content.

Figure 3: Information for developing for the Cloudogu EcoSystem in the developer documentation

What’s technically under the hood?

Docs.cloudogu.com is a Gatsby site that delivers prepared content of our documentation. Gatsby is a web page generator based on React. Through a shared library, the web frontend pulls elements from the Cloudogu platform universe such as styling and shared graphics. The technical heart of our documentation tool is a script that collects documentation components from repositories based on git sparse checkout. Each repository to be visited is defined via a JSON file. The script can handle github.com as well as our internal SCM-Manager as sources. We collect Markdown files and image files.

Figure 4: Collecting information from different sources

The gatsby-transformer-remark plugin generates the HTML content based on the collected Markdown files. In the process, the Markdown files are transformed into machine-readable “Markdown Abstract Syntax Trees” (mdAST objects) for further processing. The gatsby-transformer-remark plugin accepts additional plugins. This is where our self-developed transformer plugin comes in, which prepares the documentation according to stored rules and removes superfluous footers, for example. Furthermore, the plugin prepares relative links that work in the source repository so that they also work in our documentation.

Furthermore, we use GraphQL, a popular API query language, to automatically generate menus and tables of contents, for example.

The most exciting challenge for our developers was to create an architecture that successfully collects data from heterogeneous environments and at the same time is flexible enough to respond to changing requirements (we work according to SCRUM principles and constantly adapt requirements to new insights). Organizationally, the work on the public documentation gave us the chance to establish a uniform standard for all existing documentation.

Where do we go from here?

Just as software is never “finished”, we are constantly developing our documentation. We plan to increase the number of articles as well as the depth and to cover step by step all topics around the Cloudogu EcoSystem. Furthermore, we are thinking about an English version. We will also continue to improve the usability. For all these topics we depend on your help. Use docs.cloudogu.com and tell us in the forum what you like and where we can improve.

---

---