Eine neue Dokumentation für Joules!

2020 war die Zeit, unsere technischen Schulden in Bezug auf eine umfassende Dokumentation von Joules endlich zu bezahlen. So lesen Sie ab sofort Anleitungen zu den gängigen Vorgängen in Joules, Erklärungen der verschiedenen Funktionen und eine Einordnung von Joules in die Energiebranche an einem Ort, dem Handbuch von Joules.

Lukas Ebner
07. Januar 2021

Sagen Sie es weiter:

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:

Buch Inhalt
A: Allgemein Eine allgemeine Einführung in Joules und die Zusammenarbeit mit eins+null. Stellt den notwendigen Kontext her, um den Einsatzzweck, die Datenstruktur und das grundsätzliche Interface von Joules zu verstehen.

B: CORE

Basisfunktionalitäten rund um das Mitarbeiter-, Produkt- und Vertragsmanagement
C: ANALYTICS Beschreibung der Charts und der Dashboard-Funktionen, etc.

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!

Geht es Ihnen da genauso? Oder sehen Sie das anders?

Hinterlassen Sie uns einen Kommentar

eins+null BLOG

Unsere vorherigen Blogbeiträge

Endlich eine Dokumentation für Joules!

2020 war die Zeit, unsere technischen Schulden in Bezug auf eine umfassende Dokumentation von Joules endlich zu bezahlen. So lesen Sie ab sofort Anleitungen zu den gängigen Vorgängen in Joules, Erklärungen der verschiedenen Funktionen und eine Einordnung von Joules in die Energiebranche an einem Ort, dem Handbuch von Joules.

#eins+null
#Featured
Lukas Ebner
Jan 2021

Website-Relaunch: Compera in neuem Gewand

Nicht nur eins+null hat 2020 seinen neuen Brand gefunden, auch das Vergleichsportal compera erstrahlt seit August in einem neuen Stil.

#Digitaler Energievertrieb
Lukas Ebner
Oct 2020

Automatisch auf der sicheren Seite

Die DSGVO stellt Unternehmen innerhalb der Europäischen Union vor eine gewaltige Herausforderung. Für jeden einzelnen verarbeiteten Datensatz ist eine Unmenge an Vorschriften einzuhalten. Viele sind sich im Unklaren über die genauen Regeln und Einige kommen mit der Umsetzung der DSGVO nicht hinterher. Sie müssen nicht dazu gehören.

#Digitaler Energievertrieb
Christoph Huber
Oct 2020