report #9378
Updated by Andreas Kohlbecker about 3 years ago
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: 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: * - `//bgbmc2.bgbm.fu-berlin.de/Gruppen/BDI/EDIT-Plattform/_Latest Versions/User Manual` * als Word-Datei * Automatische Konvertierung der Word-Dokumente in PDFs * Bereitstellung im developer wiki: [PlatformDocumentation](https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/PlatformDocumentation) * ➽ *Zielgruppen*: ❶ End-Nutzer * Taxeditor "site-doc" edit:source:taxeditor|src/site * maven site doc: XML + APT files * Kompilierung im durch maven im Release-Prozess als Website * Veröffentlichung unter https://cybertaxonomy.eu/taxeditor/ * Seiten für Endnutzer ➽ *Zielgruppen*: ❶ End-Nutzer * Overview - komplett veraltet * Screenshots - leer * Manual - Link zu [PlatformDocumentation](https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/PlatformDocumentation) * Seiten für Entwickler ➽ *Zielgruppen*: ➃ Entwickler, (❸ IT-Staff) * Getting Started = "Setting up a Taxonomic Editor development environment" --> Überlappung mit [[edit:TaxonomicEditorDevelopmentEnvironment| wiki TaxonomicEditorDevelopmentEnvironment]] und #4227 * Troubleshooting --> Hier auch informationen die sich eigentlich an andere ➽ *Zielgruppen* richten: ❶ End-Nutzer, ❸ IT-Staff * Taxeditor "in-app help" edit:source:taxeditor|eu.etaxonomy.taxeditor.help (see also [#8555 Eclipse-Help-System-InfoCenter](redmine/issues/8555#Eclipse-Help-System-InfoCenter)) * HTML & XML files * ➽ *Zielgruppen*: ❶ End-Nutzer * Installationsanleitungen in der cybertaxonomy.eu Drupal-Site ➽ *Zielgruppen*: ❶ End-Nutzer, ❷ Entscheider, ❸ IT-Staff, * [server_requirements](https://cybertaxonomy.eu/setups/group/server_requirements) * [server_installation](https://cybertaxonomy.eu/setups/group/server_installation) * [taxeditor_installation](https://cybertaxonomy.eu/tax_editor/installation) --> verweist auf Manual-EDIT-Platform-01-INSTALL.pdf * [taxeditor_connection](https://cybertaxonomy.eu/setups/group/taxeditor_connection) * [dataportal_requirements](https://cybertaxonomy.eu/setups/group/dataportal_requirements) * [dataportal_installation](https://cybertaxonomy.eu/setups/group/dataportal_installation) * Web-UI (Phycobank Registration-UI) im Wiki: [RegistrationReferenceDocumentation](https://dev.e-taxonomy.eu/redmine/projects/algenregistrierung/wiki/RegistrationReferenceDocumentation), [RegistrationUserGuide](https://dev.e-taxonomy.eu/redmine/projects/algenregistrierung/wiki/RegistrationUserGuide), [FAQ](https://dev.e-taxonomy.eu/redmine/projects/algenregistrierung/wiki/RegistrationFAQ) ➽ *Zielgruppen*: ❶ End-Nutzer * spezielle "Entwickler-Dokumentation" (hier nur der Vollständigkeit wegen , aufgeführt) * [[edit:CdmLibraryDev]] * Hier auch [[edit:CdmAuthorisationAndAccessControl| Access Control, Roles, Groups]] --> ➽ *Zielgruppen*: ➃ Entwickler, ❶ End-Nutzer * diverse Files im Code? * java-doc im Code ## 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. verteilt. * 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?