Diskussion zur Verbesserung der Dokumentation

[StefanW]

Hallo Robert,
hallo Foristen,

wir hatten ja schon mehrere Anläufe, die (in Teilen bereits vorhandene) Confluence Doku zu finishen. Bislang gab es vereinzelte tolle Anstrengungen (insbesondere von Diego, der sich sehr viel Mühe gemacht hat und alle Logikmodule beschrieben hat), aber über die Diskussion der besten Struktur haben wir uns dann wieder verloren.

Womöglich muss man das ganze nochmal neu starten. Ich würde dazu ein eigenes Unterforum einrichten und dort dann nur diejenigen zur gegenseitigen Abstimmung einladen, die hier mitmachen würden und nochmal um Unterstützung werben.

Selbstverständlich liegt der Aufbau eines ordentlichen Handbuches in unserer Verantwortung als ElabNET. Auf der anderen Seite entscheide ich mich immer dann, wenn ich priorisiere, was als nächstes zu tun ist, für eine verbesserte und vereinfachte Bedienung, für neue Leistungsmerkmale und für Erweiterungen der Inline-Texte. Damit was das Zeitbudget dann schon recht erschöpft, so dass ich nicht mehr zur Confluence Doku gekommen bin.

Da wir alle zusammen ja sowohl das eine wollen ohne das andere zu lassen, wäre es sehr hilfreich, wenn ihr mir bei der Doku helfen würdet. Weil dann bleibt mehr Zeit, damit wir uns auch auf andere Themen fokussieren können.

Insbesondere ist es ja auch so, dass man den Server mit sehr vielen anderen Geräten verbinden kann (gerade mit Modbus, MQTT, UDP usw. sind das potentiell mehrere tausend Geräte) und das können wir unmöglich alles beschreiben, was man damit anstellen kann.

==> Überlegt Euch bitte, ob und wer hier unterstützen möchte, dann lege ich ein Unterforum an wo wir uns schnell und direkt abstimmen können.

lg

Stefan

[Chris M.]

Ich habe viele Sympathien für einfache Bedienung und Inline-Hilfe-Texte.
Aber bitte auch bedenken: wenn man nicht mehr weiter kommt und die Hilfe-Texte an der Stelle wo man sucht nicht stehen (z.B. weil man einfach einen falschen Ansatz gewählt hat und nun an der falschen Stelle sucht), dann wird auf Google zurück gegriffen. Und Google kann den Punkt im Handbuch finden, aber nicht in einer Inline-Hilfe.

Ich weiß, es kling gierig wenn man beides will. Aber ich versuche mich in die Situation des Anwenders zu versetzen und wie der dann agiert.

[Sensej]

Hallo zusammen,
ich versuche die Doku für mich nach diesem Format zu erstellen, weil sie für mich übersichtlicher ist und man schneller ans Ziel kommt.
Ich weiß, dass das aufwendiger ist und man viel mehr Zeit dafür braucht.

Bereich X
1. Tipp/Name(Kurzname)
2. Aufgabenstellung(ausführliche Aufgabenbeschreibung in ein paar Sätzen)
3. Abhängigkeiten(Software- und Hardware Abhängigkeiten, zusätzliches Wissen)
4. Lösung(detaillierte Beschreibung der Lösung mit Screenshots )
5. Mögliche Fehlermeldungen(detaillierte Beschreibung der Fehlermeldungen mit Screenshots)
6. Sonstiges(weitere Informationen)

MfG Juri

[Robert_Mini]

@StefanW: Bin natürlich mit dabei.
Es braucht folgende wesentliche Schritte für das Wiki:
1) Wer macht mit? In welchen Rollen?
=> Author / Reviewer und zu Beginn vor allem auch Mithilfe beim Übertragen von der KB in das Wiki - Bitte dem Aufruf von Stefan folgen und hier melden.
2) Struktur festlegen: Ich denke die letzte Struktur war bereits sehr gereift und muss nun nochmal mit der neuen Menüstruktur quergeprüft werden.
Ich kann da gerne nochmal draufschauen, final muss Stefan das freigeben.
3) Style Guide festlegen: Es gibt dazu auch einen Vorschlag im Wiki, der noch angepasst/erweitert werden müssten - Wer kann das übernehmen?
4) Übertragen der KB in die richtige Struktur in das Wiki: copy/paste, formatieren, Bilder auf Confluence übertragen und einfügen, etc. - @all: wer hilft hier mit?
5) Review und erste Freigabe - Sollte sich vom Aufwand her in Grenzen halten. Es gibt sicher ein paar Dinge die in der KB (schon wieder) veraltet sind, das kann aber dann auch später aktualisiert werden (Qualitätskriterium zu Beginn: gleichwertig oder besser als KB). Der Logik-Abschnitt ist anders zu behandeln. Da gibt es bereits eine tolle, umfassende neue Doku im Wiki, eine Querprüfung zu den KB-Inhalt macht aber sicher nochmals Sinn - ergibt sich aus den Rollen @Stefan: bitte auch um Klarstellung, was deine Erwartungen an eine Freigabe sind.

lg
Robert

PS: Neues Unterforum finde ich gut "Diskussion zur Dokumentation", wobei das später öffentlich sein sollte, damit User ihre Rückmeldungen dort posten können. Dafür gibt es im Moment keinen richtigen Ort.

[StefanW]

Hallo Robert,

2) Struktur festlegen: Ich denke die letzte Struktur war bereits sehr gereift und muss nun nochmal mit der neuen Menüstruktur quergeprüft werden.

Mein Gefühl ist da anders. Ich war gar nicht zufrieden, was zuletzt diskutiert wurde, weil es nicht zur Gesamtplanung des Systems passt.

==> Ich würde mir wünschen, dass wir die Struktur erst abstimmen. Weil das muss für die Dauer passen. Dazu möchte ich die Struktur erst in Excel usw. entwickeln, weil sich Änderungen dort schneller und einfacher durchführen lassen als eine Struktur in Confluence schon anzulegen.

3) Style Guide festlegen: Es gibt dazu auch einen Vorschlag im Wiki, der noch angepasst/erweitert werden müssten - Wer kann das übernehmen?

ja, da sollten wir drüber reden, weil es muss zum Produkt passen.

4) Übertragen der KB in die richtige Struktur in das Wiki: copy/paste, formatieren, Bilder auf Confluence übertragen und einfügen, etc. - @all: wer hilft hier mit?

Die KB ist super, aber vielfach fehlt es an einer einheitlichen Struktur und führt den Leser manchmal zuwenig in die Sache ein. Das würde ich auch gerne abstimmen.

PS: Neues Unterforum finde ich gut "Diskussion zur Dokumentation", wobei das später öffentlich sein sollte, damit User ihre Rückmeldungen dort posten können. Dafür gibt es im Moment keinen richtigen Ort.

Nein, bitte nicht später öffentlich.

Ich muss stets ganz genau aufpassen was ich schreibe und wer was wie wann auf welche Seite gleich oder später auslegen könnte. Das ist sehr anstrengend für mich, stets auf meine öffentlichen Worte achten zu müssen. Daher wäre ich über ein beschränktes Unterforum sehr froh, in dem ich etwas freier sprechen kann und insbesondere geht es ja auch künftig darum, dass ein Handbuchabschnitt für ein neues Feature schon vorbereitet wird, bevor wir überhaupt veröffentlichen, dass es ein neues Leistungsmerkmal gibt.

Darum wünsche ich mir ein privates Unterforum und dass es dann auch auf Dauer "Privat" bleiben soll.

lg

Stefan

[Robert_Mini]

Mein Gefühl ist da anders. Ich war gar nicht zufrieden, was zuletzt diskutiert wurde, weil es nicht zur Gesamtplanung des Systems passt.

Schau mal in Confluence rein - hab die Stuktur dort gerade nochmals auf die neue Menüstruktur angepasst.
Soweit sollte das von der Gesamtplanung nicht mehr weg sein.

Es braucht aus meiner Sicht vor allem eine Richtschnur, bis wohin Dinge in dieser an das Menü angepassten Struktur liegen sollen und wofür es dann noch eigene Unterpunkte gibt, die es im Menü nicht gibt:
- Einfache Beispiellogiken im Logik-Kapitel? Umfassende Custom-Logiken in einem eigenen Abschnitt oder unter LE?
- Container-Beschreibungen im Portainer Kapitel?
- Abgestimmte Feature Requests?
- ...

Nein, bitte nicht später öffentlich.

Kein Problem. Ich meinte hauptsächlich, das es auch ein öffentliches Unterforum geben sollte, in dem jeder Nutzer sein Feedback geben kann.

Die KB ist super, aber vielfach fehlt es an einer einheitlichen Struktur und führt den Leser manchmal zu wenig in die Sache ein. Das würde ich auch gerne abstimmen.

Das stimmt, ist aber leider auch schwierig, da vieles an mehreren Stellen passen würde. Aus meiner Sicht ist eine gute Verlinkung innerhalb des Wikis entscheidend.

Abschließender Kommentar: Ich denke die Balance aus Qualität und Zeit ist entscheidend. Eine perfekt geplante Struktur wär natürlich schön, weil eine umfassende Umstrukturierung schwierig ist. Aber eine Planung bis ins letzte Detail wird nicht funktionieren, es braucht da auch ein wenig Scrum.
Perfektionismus ist hier das falsche Ziel und vor allem darfst du nicht das Bottleneck sein!

lg
Robert

[StefanW]

Hallo Robert,

Schau mal in Confluence rein - hab die Stuktur dort gerade nochmals auf die neue Menüstruktur angepasst.

Danke - und veröffentlicht.

Ich muss mich noch ein wenig mehr einlesen in Confluence, aber das Confluence Wiki ist bereits öffentlich und wird somit womöglich (jederzeit) von Google und anderen Suchmaschinen gefunden und mein Gefühl sagt mir, dass dies womöglich so nicht die richtige Vorgehensweise ist. Ich glaube, man braucht auch erstmal ein Template und legt eine Struktur dort mit Template an - und auch stückweise mit dem Fortschritt, damit man Anpassungen am Template besser mitnehmen kann. Ich glaube, nachträglich ist das ein größerer Aufwand.

==> Bitte lass uns erst planen und abstimmen.

Ich denke nun darüber nach, das bereits geschaffene Confluence für die Öffentlichkeit zu schließen und künftig als Staging zu benutzen und eine neue öffentliche Instanz aufzuziehen, in der dann erst nach einem Review-Prozess die freigegebenen Artikel - händisch selektiert - einkopiert werden. Ich denke, ein ordentliches Release-Management macht da durchaus Sinn, auch wenn es damit doppelt soviel Arbeit ist, was einem schnellen Ergebnis nicht förderlich ist.

Soweit sollte das von der Gesamtplanung nicht mehr weg sein.

Ich muss da erst nochmal in mich gehen.

Es braucht aus meiner Sicht vor allem eine Richtschnur, bis wohin Dinge in dieser an das Menü angepassten Struktur liegen sollen und wofür es dann noch eigene Unterpunkte gibt, die es im Menü nicht gibt:

Richtig.

Es mag zwar typisch sein für Handbücher, aber ich mag eine Struktur, die sich einfach nur nach dem Menü ausrichtet eher nicht, weil die Benutzer sich nicht von oben nach unten durchklicken, sondern für das Einrichten von Aufgaben ("wie bringen ich einen 1-Wire Wert über KNX in die Visu") über alle Bereiche müssen und daher auch eine aufgabenzentrische Betrachtung Sinn macht.

Kein Problem. Ich meinte hauptsächlich, das es auch ein öffentliches Unterforum geben sollte, in dem jeder Nutzer sein Feedback geben kann.

Da fällt uns sicher etwas ein in der Kategorie "Timberwolf Server" usw.

Insgesamt müssen mir vor allem Beobachten, wo sich für einen Nutzer fragen ergeben, die derjenige im Forum stellt und dann die Doku daraufhin überprüfen, ob dies auch gut enthalten ist.

Aus meiner Sicht ist eine gute Verlinkung innerhalb des Wikis entscheidend.

Ja, richtig.

Abschließender Kommentar: Ich denke die Balance aus Qualität und Zeit ist entscheidend. Eine perfekt geplante Struktur wär natürlich schön, weil eine umfassende Umstrukturierung schwierig ist. Aber eine Planung bis ins letzte Detail wird nicht funktionieren, es braucht da auch ein wenig Scrum.

Keine Sorge, machen wir nicht. Aber nur Agil drauflos ohne Planung und Abstimmung ist auch nicht zielführend. Obwohl wir bei der Entwicklung des Servers recht agil arbeiten, gibt es trotzdem einen Zwei-Jahres-Plan und eine gewisse Struktur hinsichtlich neuer Leistungsmerkmale.


==> Ich habe den separaten Doku-Bereich angelegt und die frühere Diskussion von anderer Stelle dorthin kopiert.

==> Sobald ich dazu komme, werde ich einen überarbeiteten Vorschlag

lg

Stefan

[StefanW]

Hallo Chris,

Aber bitte auch bedenken: wenn man nicht mehr weiter kommt und die Hilfe-Texte an der Stelle wo man sucht nicht stehen (z.B. weil man einfach einen falschen Ansatz gewählt hat und nun an der falschen Stelle sucht), dann wird auf Google zurück gegriffen. Und Google kann den Punkt im Handbuch finden, aber nicht in einer Inline-Hilfe.

Kein Thema, es ging nie darum, ob ein ordentliches Handbuch, zusätzlich zu Inline-Hilfe und Knowledge-Base & Forum nicht auch Sinn macht. Es ist völlig klar, das wir das benötigen.

Ich weiß, es kling gierig wenn man beides will. Aber ich versuche mich in die Situation des Anwenders zu versetzen und wie der dann agiert.

Aber das Thema lautet Priorisierung. Wir arbeiten alle soviel wir nur irgendwie schaffen und neue Leistungsmerkmale sind den Nutzern wichtiger, zumindest in der überwiegenden öffentlichen Rezeption. Zumal es viele Nutzer mit Handbuchallergie gibt und eine möglichst einfache Bedienung des Produktes allen Nutzern hilft, auch denen die nicht ins Handbuch sehen. Darum haben wir das präferiert.

Wer sich die Unterschiede zwischen Version 1.5 und nun der 1.6 ansieht, wird an sehr vielen Stellen ganz deutliche Verbesserungen sehen die auch in den betreffenden Bereichen zu einem erheblichen Rückgang an Fragen im Forum geführt haben. Stellenweise war es so ruhig, dass wir schon um das Forum geführt hatten. Ich lese daraus einen gewissen Erfolg der bereits umgesetzten Maßnahmen für Nutzbarkeit und der KB heraus.

Beides haben wir bisher nicht geschafft, aber wir arbeiten daran.

lg

Stefan

[starwarsfan]

Hallo miteinander,

nix für ungut aber für meine Begriffe wird das Ganze jetzt völlig übertrieben!

@StefanW, für mich liesst sich das was da nun entstehen soll nicht mehr nach einem Wiki von Usern für User sondern nach einer druckreifen Gesamtdokumentation. Nochmal von vorne anfangen? Noch eine neue Instanz und dann nur "approved Content" dort drin? Wie kommst Du denn auf den Trichter!? Ihr habt doch so schon zu wenig Leute!

Lasst doch die interessierten Leute einfach ihre Wiki-Artikel schreiben! Ein Wiki lebt von der Mitarbeit, nicht der Reglementierung aber genau dahin driftet das im Moment sehr stark ab. Strukturelle Änderungen sind absolut trivial und damit ist es auch im Nachhinein ein leichtes, ganze Artikel irgendwo anders einzusortieren oder die Menüstruktur zu modifizieren. Je nachdem wie es sich entwickelt, sieht man dann sehr viel konkreter, ob die momentane Gliederung/Struktur/whatever praktikabel ist oder nicht, anstatt das vorher haarklein vorauszuplanen um dann festzustellen, dass es doch nicht so prickelnd ist.

Just my two cents...

[StefanW]

@StefanW, für mich liesst sich das was da nun entstehen soll nicht mehr nach einem Wiki von Usern für User sondern nach einer druckreifen Gesamtdokumentation.

Sorry, ich wollte eigentlich auch kein Wiki von User zu User, sondern das sollte schon mehr in Richtung offizielle Doku gehen. Wirklich sehr gerne unter Beteiligung ausgewählter Nutzer, aber ich wollte schon, dass ein gewisser roter Faden erkennbar ist.

Nochmal von vorne anfangen? Noch eine neue Instanz und dann nur "approved Content" dort drin? Wie kommst Du denn auf den Trichter!? Ihr habt doch so schon zu wenig Leute!

Die Überlegung ist, einen Staging Bereich und einen freigegebenen Bereich zu schaffen. So machen wir das schließlich mit der Software auch.

Ich bin derzeit sehr beschäftigt und kann das jetzt nicht umfangreich diskutieren, weil ich habe gerade in einer anderen Sache einen ziemlichen Termindruck. Ich melde mich hierzu wieder zurück, wenn ich das dann auch gut begleiten kann.

lg

Stefan