Project

General

Profile

report #9378

Meeting EDIT Platform documentation 2021-02-22

Added by Andreas Kohlbecker 11 months ago. Updated 9 months ago.

Status:
Closed
Priority:
Highest
Category:
Documentation
Start date:
01/11/2021
Due date:
% Done:

100%

Audience:

Description

WebEx Meeting: https://fu-berlin.webex.com/fu-berlin/j.php?MTID=ma3d5a3cfabd30fbfdccb11e37122a1e4

Teilnehmer:

  • Anton Güntsch
  • Andreas Kohlbecker
  • Andreas Müller
  • Katja Luther
  • Walter Berendsohn

Thema

Besprochen werden sollen Fragen zur der Dokumentation der EDIT Plattform, die sich vornehmlich an Nutzer richtet. Nicht bespochen werden sollen Dokumentationen, die sich ausschließlich an Entwickler richten oder die technischer Natur sind wie API-Dokus, Web-Service Doku., etc.

  • Wo soll die Dokumentation veröffentlicht, bereitgestellt werden und
    • in welchen Formaten: HTML, PDF, ...?
  • Brauchen wir eine In-App Dokumentation im Taxeditor?
  • Modularisierung der Dokumentation? (Allgemeine Doku vs. Workshop-Anleitungen)
  • (Workflow und Tools) eventuell in separatem Meeting

Ablauf:

  1. Überblick
    • Zielgruppen der Dokumentation
    • Wo es derzeit EDIT-Plattform Dokumentation gibt
    • Probleme derzeit
  2. Diskussion und Antworten auf die eingangs aufgeworfenen Fragen
  3. Weitere Vorgehensweise? Neuer Termin?

Ausgangslage:

Zielgruppen für Dokumentation:

  • ❶ End-Nutzer
    • Taxonomist
    • Teachers
    • Postgraduates
    • Students
    • Assistants
    • Project Admins
  • ❷ Entscheider
  • ❸ IT-Abteilung und -Support (--> System Requirements, Troubleshooting) - Informationen zu Voraussetzungen einer Installation und Tips zur Vor-Ort-Hilfe ohne das das EDIT-Team gebraucht wird.
  • ➃ Entwickler

Bestehende Dokumentation:

Probleme derzeit:

  • Dokumentation an verschiedenen Stellen verteilt
  • Dokumentation in uneinheitlichen Ausgangs und Endformaten:
    • Endformate:
      • PDF: gut für Druck, schlecht geeignet für Mobilgeräte, schlecht integrierbar in Produkte wie Taxeditor
      • HTML: Vielseitig verwendbar, gut für unterschiedliche Typen von Endgeräten.
  • Anpassung Erweiterung der Dokumentation bei Implementierungsänderungen: Es gibt keinen direkt Weg im Workflow vom Schritt "Implementierung fertig und Ticket geschlossen" zu "Aktualisierung der Dokumentation". Dies betrifft besonders des Taxeditor. Die folgenden Fragen können nur nach manuellem Vergleich der bestehenden Doku mit dem Taxeditor geantwortet werden --> Unklarheit darüber welche Teile der Dokumentation veraltet sind. Dies kann derzeit nur durch den Austausch im Team, durch Anfragen von Nutzern oder manuellen Vergleich herausgefunden werden.
    • Kann das besser organisiert werden?
    • Gibt es sinnvolle technische Hilfsmittel?
    • Wer ist zuständig für welche Änderungen in der Doku? Kleinere Änderungen durch Entwickler gleich in Doku eintragen? Für Größere Änderungen Ticket?
  • Trennung von Dokumentation und Code.
  • Worddoc/PDFs: Vermischung von allgemeiner Dokumentation zum Taxeditor und sehr spezifischer Workshopanleitungen --> Redundanz --> Modularisierung möglich?
  • Sharing und Synchronisierung über NT-Shares
    • Handling von Synchonisierierungsproblemen intransparent
    • keine implizite Versionierung
    • unter Linux: häufig NT_STATUS_ACCOUNT_LOCKED_OUT, nach Synchronisierung offline gehen --> Mülleimer blockiert, Setup kompliziert und fehleranfällig,

Mögliche Lösungsvorschläge

  • End-Nutzer Doumentation zentral an einem Ort
  • Anwedung des Prinzips "Everything as Code"?
  • Dokumentation in Versionsverwaltung-System (VCS) wie git?

Ergebnisprotokoll des Meetings: https://wiki.bgbm.org/bdinotes/index.php/BDI_299


Related issues

Related to EDIT Platform Etablierung - task #8555: Evaluate document format and management for the documentation In Progress 09/19/2019

History

#1 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#2 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#3 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#4 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#5 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#6 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#7 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#8 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#9 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#10 Updated by Andreas Kohlbecker 10 months ago

  • Related to task #8555: Evaluate document format and management for the documentation added

#11 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#12 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#13 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#14 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#15 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#16 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#17 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#18 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#19 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#20 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#21 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#22 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#23 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#24 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#25 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#26 Updated by Andreas Kohlbecker 10 months ago

  • Description updated (diff)

#27 Updated by Andreas Kohlbecker 9 months ago

  • Subject changed from Meeting EDIT Platform documentation to Meeting EDIT Platform documentation 2021-02-22

#28 Updated by Andreas Kohlbecker 9 months ago

  • Category changed from PlatformSetup to Documentation

#29 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)

#30 Updated by Andreas Kohlbecker 9 months ago

  • Description updated (diff)
  • Status changed from New to Closed
  • % Done changed from 0 to 100

Ergebnisprotokoll des Meetings: https://wiki.bgbm.org/bdinotes/index.php/BDI_299

#31 Updated by Andreas Müller 9 months ago

Sollten wir das nicht lieber auf eine WikiSeite schreiben als in ein Ticket?

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 40 MB)