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

Leichter navigieren in Joules

Ab dem nächsten Update wandert die Navigation in Joules von der Seite an den oberen Bildschirmrand. Damit können Sie leichter und von jedem Ort in Joules intuitiv navigieren.

#Digitaler Energievertrieb
Eveline Eckert
Oct 2021

Sommer, Sonne, Firmenfeier

Das letzte Jahr hat uns etwas aus der Übung gebracht, was das Feiern betrifft. Viele Tage im Homeoffice und halbleere Büros haben die Sehnsucht nach einer Feier umso größer werden lassen. So war das Sommerfest in diesem Jahr eine Feier der Gemeinschaft, endlich wieder als Gruppe zusammen zu sein.

#eins+null
#Featured
Anna Walberer
Sep 2021

Workflows managen in Joules

In Joules können Sie mit einer große Menge an statusbezogenen Abläufen. Damit das nicht unübersichtlich wird bietet Ihnen der Workflowmanager eine Übersicht über alle statusbasierten Events und die Vertragsstatus, die sie triggern.

#Digitaler Energievertrieb
Eveline Eckert
Aug 2021