- UI/UX Expert -
Philipp works at Cloudogu to make it a bit easier for users to work with software. He has many years of experience in various design disciplines. Nevertheless, he is always amazed at the creative ways in which users use products.
The principle of good software is to present as many complex relationships as possible in an easily understandable way. Thus, our Cloudogu EcoSystem (CES) looks pretty simple even though it hides extensive operations under the surface. Nevertheless, the CES 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.
Docs.cloudogu.com provides a wide variety of information related to the Cloudogu EcoSystem:
The documentation is especially intended for end users, developers and administrators, as well as anyone interested in the Cloudogu EcoSystem.
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.
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.
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 CES 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.
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.
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 myCloudogu 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.
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.
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.