Warum es bisher keine Doku gab

Unter dem Begriff "technische Schulden" versteht man in der Informatik das Aufschieben wichtiger technischer oder organisatorischer Massnahmen während der Implementierung eines Software-Projekts: Dabei werden für eine kurzfristige Zeitersparnis bei der Umsetzung langfristig immer größere und drängender werdende strukturelle Probleme in Kauf genommen. Und ein geradezu klassischer Fall von solchen technischen Schulden ist die bis vor Kurzem noch fehlende Software-Dokumentation von Joules.

Denn beim ersten Entwurf von Joules im Jahr 2011 hatten wir einfach andere Sorgen: Gibt es überhaupt einen Markt für unser Produkt? Welche Features müssen wir bauen? Wo finden wir Kunden? Für so eine "Nebensächlichkeit" wie eine saubere Dokumentation blieb dabei natürlich keine Zeit. Zudem wurde das Fehlen einer Dokumentation bei unseren ansonsten in der Regel notorisch anspruchsvollen Kunden nur selten problematisiert.

Und so wurde die Dokumentation Jahr für Jahr auf die lange Bank geschoben. Und je länger man ein Problem aufschiebt, umso schwieriger wird es natürlich, dann irgendwann doch noch aus dem Quark zu kommen.

Völlig klar war immer, dass das Fehlen der Dokumentation verschiedene Folgeprobleme verursacht: Denn Kunden, die sich im System nicht zurecht finden, produzieren Rückfragen und Rückfragen belastet die Kundenzufriedenheit.

Schliesslich haben wir im Corona-Jahr 2020 die Gelegenheit zur Begleichung unserer technischen Schulden dann beim Schopf gepackt: Eine vollständige Marketing-Abteilung im Home Office, durstig nach Arbeit – eine solche Chance darf man nicht verstreichen lassen.

So nutzen Sie die neue Joules Dokumentation

Kurz vor Weihnachten mit Joules-Version 1.116 wurde nun das erste Batch der Dokumentationstexte für unsere Kunden zugänglich gemacht. Sie finden die offizielle Joules-Dokumentation unter https://handbuch.einsundnull.de Sie authentifizieren sich mit Ihrem Redmine-Account.

Alternativ finden Sie am unteren rechten Seitenrand in Joules ein neues Element, mit dem Sie direkt zum jeweilig passenden Bereich im Handbuch springen können.

Nach dem Login sehen Sie unsere eigens entwickelte Handbuch App. In der linken Spalte befinden sich die bereits veröffentlichten Bücher, Kapitel und Seiten. In der Mitte befindet sich der jeweils gewählte Text. Auf der rechten Seite finden Sie eine navigierbare Gliederung des aktuellen Artikels.

Bücher, Kapitel und Seiten

Das Handbuch ist mit Hilfe der Software "Bookstack" erstellt, dem von eins+null auch intern eingesetztem Dokumentationssystem. In Bookstack ist es möglich, umfangreiche Textsammlungen in Regale ("Shelfes"), Bücher, Kapitel und Seiten aufzugliedern. Für die vorliegende Dokumentation ergibt sich daraus die folgende Aufteilung:

Innerhalb der Bücher werden thematisch zusammengehörige Texte zu "Kapiteln" zusammengefasst. Beispielsweise sind alle Texte zu den Bereichen "Tarifrechner", "Tarife verwalten", und allen damit zusammenhängenden Workflow-Anleitungen in einem Kapitel "Produktmanagement" gruppiert.

Textarten

In der Joules-Dokumentation werden Ihnen drei Textarten begegnen:

• Kontexte: In diesen Texten werden Zusammenhänge und Hintergründe des Joules-System erklärt. Während Referenzen und Anleitungen in der Regel mit einem konkreten Bereich in Joules verbunden sind, sind Kontexte allgemein gehalten. Sie erklären das "Warum" des Systems.
• Referenzen: Zu jedem Bereich in Joules gibt es eine Referenz. Referenz-Seiten beschreiben einfach, was auf einer Seite zu sehen ist, und was der User damit tun kann.
• Anleitungen: Anleitungen beschreiben Schritt für Schritt die Durchführung einer Aufgabenstellung im System, z.B. "Einen neuen User anlegen", "einen Tarif pflegen" etc.

So gehts mit der Dokumentation weiter

Für den Launch des Handbuchs haben wir die folgenden Bereiche vollständig dokumentiert:

Mit dem Anfang des neuen Jahres haben wir nun die Dokumentation des PARTNER-Moduls in Angriff genommen. Unser Team schafft in der Woche im Schnitt ca 15 Seiten Text. Es ist also zu erwarten, dass wir Ihnen bereits Ende März diesen neuen Bereich in der Plattform freischalten werden.

Bis dahin gibt es mit den fertiggestellten Bereichen "Allgemein", "CORE" und "ANALYTICS" bereits 600 Seiten Lesestoff, ohne Bilder, wohlgemerkt – Ideal zum Schmökern an langen Winterabenden!

Haben Sie Feedback zur Doku? Schreiben Sie uns Ihre Meinung in das Kommentarfeld!