Project

General

Profile

Actions

report #9378

closed

Meeting EDIT Platform documentation 2021-02-22

Added by Andreas Kohlbecker about 3 years ago. Updated about 3 years ago.

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

100%

Estimated time:
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 documentationClosedAndreas Kohlbecker09/19/2019

Actions
Actions

Also available in: Atom PDF