EDIT Platform Etablierung: Issueshttps://dev.e-taxonomy.eu/redmine/https://dev.e-taxonomy.eu/redmine/redmine/favicon.ico?14691914852021-01-11T10:53:34ZEDIT Project Management
Redmine report #9378 (Closed): Meeting EDIT Platform documentation 2021-02-22https://dev.e-taxonomy.eu/redmine/issues/93782021-01-11T10:53:34ZAndreas Kohlbecker
<p>WebEx Meeting: <a href="https://fu-berlin.webex.com/fu-berlin/j.php?MTID=ma3d5a3cfabd30fbfdccb11e37122a1e4">https://fu-berlin.webex.com/fu-berlin/j.php?MTID=ma3d5a3cfabd30fbfdccb11e37122a1e4</a></p>
<a name="Teilnehmer"></a>
<h2 >Teilnehmer:<a href="#Teilnehmer" class="wiki-anchor">¶</a></h2>
<ul>
<li>Anton Güntsch</li>
<li>Andreas Kohlbecker</li>
<li>Andreas Müller</li>
<li>Katja Luther</li>
<li>Walter Berendsohn</li>
</ul>
<a name="Thema"></a>
<h2 >Thema<a href="#Thema" class="wiki-anchor">¶</a></h2>
<p>Besprochen werden sollen Fragen zur der Dokumentation der EDIT Plattform, die sich vornehmlich an Nutzer richtet. Nicht bespochen werden sollen Dokumentationen, die sich <strong>ausschließlich</strong> an Entwickler richten oder die technischer Natur sind wie API-Dokus, Web-Service Doku., etc. </p>
<ul>
<li>Wo soll die Dokumentation veröffentlicht, bereitgestellt werden und
<ul>
<li>in welchen Formaten: HTML, PDF, ...?</li>
</ul></li>
<li>Brauchen wir eine In-App Dokumentation im Taxeditor?</li>
<li>Modularisierung der Dokumentation? (Allgemeine Doku vs. Workshop-Anleitungen)</li>
<li>(Workflow und Tools) eventuell in separatem Meeting</li>
</ul>
<a name="Ablauf"></a>
<h2 >Ablauf:<a href="#Ablauf" class="wiki-anchor">¶</a></h2>
<ol>
<li>Überblick
<ul>
<li>Zielgruppen der Dokumentation</li>
<li>Wo es derzeit EDIT-Plattform Dokumentation gibt</li>
<li>Probleme derzeit</li>
</ul></li>
<li>Diskussion und Antworten auf die eingangs aufgeworfenen Fragen</li>
<li>Weitere Vorgehensweise? Neuer Termin? </li>
</ol>
<a name="Ausgangslage"></a>
<h2 >Ausgangslage:<a href="#Ausgangslage" class="wiki-anchor">¶</a></h2>
<a name="Zielgruppen-für-Dokumentation"></a>
<h3 >Zielgruppen für Dokumentation:<a href="#Zielgruppen-für-Dokumentation" class="wiki-anchor">¶</a></h3>
<ul>
<li>❶ End-Nutzer
<ul>
<li>Taxonomist</li>
<li>Teachers</li>
<li>Postgraduates</li>
<li>Students</li>
<li>Assistants</li>
<li>Project Admins</li>
</ul></li>
<li>❷ Entscheider</li>
<li>❸ 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.</li>
<li>➃ Entwickler</li>
</ul>
<a name="Bestehende-Dokumentation"></a>
<h3 >Bestehende Dokumentation:<a href="#Bestehende-Dokumentation" class="wiki-anchor">¶</a></h3>
<ul>
<li>- <code>//bgbmc2.bgbm.fu-berlin.de/Gruppen/BDI/EDIT-Plattform/_Latest Versions/User Manual</code>
<ul>
<li>als Word-Datei</li>
<li>Automatische Konvertierung der Word-Dokumente in PDFs</li>
<li>Bereitstellung im developer wiki: <a href="https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/PlatformDocumentation" class="external">PlatformDocumentation</a></li>
<li>➽ <em>Zielgruppen</em>: ❶ End-Nutzer</li>
</ul></li>
<li>Taxeditor "site-doc" <a class="source" href="https://dev.e-taxonomy.eu/redmine/projects/edit/repository/taxeditor/entry/src/site">edit:source:taxeditor|src/site</a>
<ul>
<li>maven site doc: XML + APT files</li>
<li>Kompilierung im durch maven im Release-Prozess als Website</li>
<li>Veröffentlichung unter <a href="https://cybertaxonomy.eu/taxeditor/">https://cybertaxonomy.eu/taxeditor/</a></li>
<li>Seiten für Endnutzer ➽ <em>Zielgruppen</em>: ❶ End-Nutzer
<ul>
<li>Overview - komplett veraltet</li>
<li>Screenshots - leer </li>
<li>Manual - Link zu <a href="https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/PlatformDocumentation" class="external">PlatformDocumentation</a></li>
</ul></li>
<li>Seiten für Entwickler ➽ <em>Zielgruppen</em>: ➃ Entwickler, (❸ IT-Staff)
<ul>
<li>Getting Started = "Setting up a Taxonomic Editor development environment" --> Überlappung mit <a class="wiki-page" href="https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/TaxonomicEditorDevelopmentEnvironment"> wiki TaxonomicEditorDevelopmentEnvironment</a> und <a class="issue tracker-5 status-4 priority-12 priority-high14" title="feature request: handle generated resources in eclipse workspace (Feedback)" href="https://dev.e-taxonomy.eu/redmine/issues/4227">#4227</a></li>
<li>Troubleshooting --> Hier auch informationen die sich eigentlich an andere ➽ <em>Zielgruppen</em> richten: ❶ End-Nutzer, ❸ IT-Staff</li>
</ul></li>
</ul></li>
<li>Taxeditor "in-app help" <a class="source" href="https://dev.e-taxonomy.eu/redmine/projects/edit/repository/taxeditor/entry/eu.etaxonomy.taxeditor.help">edit:source:taxeditor|eu.etaxonomy.taxeditor.help</a> (see also <a href="redmine/issues/8555#Eclipse-Help-System-InfoCenter" class="external">#8555 Eclipse-Help-System-InfoCenter</a>)
<ul>
<li>HTML & XML files</li>
<li>➽ <em>Zielgruppen</em>: ❶ End-Nutzer</li>
</ul></li>
<li>Taxeditor "Moureover-Hilfe": Für bestimmte UI-Elemente gibt es Hilfetexte, die direkt im Code zum jeweiligen UI-Element existieren. </li>
<li>Installationsanleitungen in der cybertaxonomy.eu Drupal-Site ➽ <em>Zielgruppen</em>: ❶ End-Nutzer, ❷ Entscheider, ❸ IT-Staff,
<ul>
<li><a href="https://cybertaxonomy.eu/setups/group/server_requirements" class="external">server_requirements</a></li>
<li><a href="https://cybertaxonomy.eu/setups/group/server_installation" class="external">server_installation</a></li>
<li><a href="https://cybertaxonomy.eu/tax_editor/installation" class="external">taxeditor_installation</a> --> verweist auf Manual-EDIT-Platform-01-INSTALL.pdf</li>
<li><a href="https://cybertaxonomy.eu/setups/group/taxeditor_connection" class="external">taxeditor_connection</a></li>
<li><a href="https://cybertaxonomy.eu/setups/group/dataportal_requirements" class="external">dataportal_requirements</a></li>
<li><a href="https://cybertaxonomy.eu/setups/group/dataportal_installation" class="external">dataportal_installation</a></li>
</ul></li>
<li>Web-UI (Phycobank Registration-UI) im Wiki: <a href="https://dev.e-taxonomy.eu/redmine/projects/algenregistrierung/wiki/RegistrationReferenceDocumentation" class="external">RegistrationReferenceDocumentation</a>, <a href="https://dev.e-taxonomy.eu/redmine/projects/algenregistrierung/wiki/RegistrationUserGuide" class="external">RegistrationUserGuide</a>, <a href="https://dev.e-taxonomy.eu/redmine/projects/algenregistrierung/wiki/RegistrationFAQ" class="external">FAQ</a> ➽ <em>Zielgruppen</em>: ❶ End-Nutzer</li>
<li>spezielle "Entwickler-Dokumentation" (hier nur der Vollständigkeit wegen , aufgeführt)
<ul>
<li><a class="wiki-page" href="https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/CdmLibraryDev">CdmLibraryDev</a>
<ul>
<li>Hier auch <a class="wiki-page" href="https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/CdmAuthorisationAndAccessControl"> Access Control, Roles, Groups</a> --> ➽ <em>Zielgruppen</em>: ➃ Entwickler, ❶ End-Nutzer</li>
</ul></li>
<li>diverse Files im Code?</li>
<li>java-doc im Code</li>
</ul></li>
</ul>
<a name="Probleme-derzeit"></a>
<h2 >Probleme derzeit:<a href="#Probleme-derzeit" class="wiki-anchor">¶</a></h2>
<ul>
<li>Dokumentation an verschiedenen Stellen verteilt </li>
<li>Dokumentation in uneinheitlichen Ausgangs und Endformaten:
<ul>
<li>Endformate:
<ul>
<li>PDF: gut für Druck, schlecht geeignet für Mobilgeräte, schlecht integrierbar in Produkte wie Taxeditor</li>
<li>HTML: Vielseitig verwendbar, gut für unterschiedliche Typen von Endgeräten. </li>
</ul></li>
</ul></li>
<li>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.
<ul>
<li>Kann das besser organisiert werden? </li>
<li>Gibt es sinnvolle technische Hilfsmittel?</li>
<li>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?<br></li>
</ul></li>
<li>Trennung von Dokumentation und Code.</li>
<li>Worddoc/PDFs: Vermischung von allgemeiner Dokumentation zum Taxeditor und sehr spezifischer Workshopanleitungen --> Redundanz --> Modularisierung möglich?<br></li>
<li>Sharing und Synchronisierung über NT-Shares
<ul>
<li>Handling von Synchonisierierungsproblemen intransparent</li>
<li>keine implizite Versionierung</li>
<li>unter Linux: häufig NT_STATUS_ACCOUNT_LOCKED_OUT, nach Synchronisierung offline gehen --> Mülleimer blockiert, Setup kompliziert und fehleranfällig, </li>
</ul></li>
</ul>
<a name="Mögliche-Lösungsvorschläge"></a>
<h2 >Mögliche Lösungsvorschläge<a href="#Mögliche-Lösungsvorschläge" class="wiki-anchor">¶</a></h2>
<ul>
<li>End-Nutzer Doumentation zentral an einem Ort</li>
<li>Anwedung des Prinzips "Everything as Code"?</li>
<li>Dokumentation in Versionsverwaltung-System (VCS) wie git?</li>
</ul>
<hr>
<p><strong>Ergebnisprotokoll</strong> des Meetings: <a href="https://wiki.bgbm.org/bdinotes/index.php/BDI_299">https://wiki.bgbm.org/bdinotes/index.php/BDI_299</a></p>
task #8555 (Closed): Evaluate document format and management for the documentationhttps://dev.e-taxonomy.eu/redmine/issues/85552019-09-19T15:25:45ZAndreas Kohlbecker
<ol>
<li>research on suitable document formats</li>
<li>documentation within the taxeditor would be preferable (see <a class="wiki-page" href="https://dev.e-taxonomy.eu/redmine/projects/edit-platform-etablierung/wiki/Meeting_2019-09-07">Meeting_2019-09-07</a>:
<ul>
<li>In-App_Doku im Taxeditor: (see <a class="issue tracker-6 status-5 priority-11 priority-default closed" title="task: Evaluate document format and management for the documentation (Closed)" href="https://dev.e-taxonomy.eu/redmine/issues/8555">#8555</a>)
<ul>
<li>via Tooltips</li>
<li>F1 --> Eclipse RCP Helpsystem</li>
<li>Export als PDF</li>
</ul></li>
</ul></li>
</ol>
<hr>
<a name="Eclipse-Help-System-InfoCenter"></a>
<h2 >Eclipse Help System (InfoCenter)<a href="#Eclipse-Help-System-InfoCenter" class="wiki-anchor">¶</a></h2>
<p>Resources:</p>
<ul>
<li><a href="https://wiki.eclipse.org/Platform/InfoCenter" class="external">Platform/InfoCenter</a></li>
<li><a href="http://www.eclipse.org/articles/article.php?file=Article-AddingHelpToRCP/index.html" class="external">Adding Help Support to a Rich Client Platform (RCP) Application</a></li>
<li><a href="http://www.eclipse.org/articles/Article-Authoring-With-Eclipse/index.html#eclipse-transformation" class="external">Authoring with Eclipse - Technical Documentations with DockBook and DITA</a>
<ul>
<li><a href="https://wiki.eclipse.org/Authoring_Eclipse_Help_Using_DITA" class="external">Authoring Eclipse Help Using DITA</a> [<em>2 September 2009</em>]</li>
<li><a href="http://wiki.eclipse.org/Authoring_Eclipse_Help_Using_DocBook" class="external">Authoring Eclipse Help Using DocBook</a> [<em>2 September 2009</em>]</li>
<li><a href="https://www.vogella.com/tutorials/EclipseRCPHelpSystem/article.html" class="external">vogella - EclipseRCPHelpSystem</a></li>
<li><a href="http://www.sagehill.net/docbookxsl/EclipseHelp.html" class="external">Sagehill - DocBook XSL: The Complete Guide - Eclipse Platform help system</a></li>
</ul></li>
</ul>
<p>The content for the eclipse help system consists of <strong>TOC XML</strong> files in which the structure of the documentation is defined. The TOC-XML files reference the content which is written in <strong>HTML</strong>.</p>
<p>The help system (since 3.3) has extension points for <strong>content producers</strong> that programmatically generate help content including a table of contents, keyword index, and content pages. This can be useful when converting documentation from some other format into HTML.(<a href="http://www.eclipse.org/articles/article.php?file=Article-AddingHelpToRCP/index.html" class="external"></a>) --> <strong>TODO</strong>: <em>which formats are supported?</em></p>
<p>The eclipse wiki describes techniques to write the documentation in DocBook or DITA and to transform these into the eclipse help structure of TOC-XML and HTML files. --> <strong>TODO</strong>: are there maven plugins supporting the transformation?</p>
<a name="DocBook-amp-DITA"></a>
<h2 >DocBook & DITA<a href="#DocBook-amp-DITA" class="wiki-anchor">¶</a></h2>
<p>Documentations created in DocBook and DITA can be modularized (<a href="http://www.sagehill.net/docbookxsl/ModularDoc.html">http://www.sagehill.net/docbookxsl/ModularDoc.html</a>). Books can be assembled from individual chapter files whereas chapters can be hierarchically nested at arbitrary levels. DockBook 5.0 and DITA also support the concept of topics. </p>
<p><strong>WYSIWYG editors for DocBook and DITA:</strong></p>
<ul>
<li><a href="https://www.eclipse.org/vex/" class="external">Vex</a> - Eclipse plugin
<ul>
<li>DocBook, DITA?</li>
<li>OpenSource & free</li>
<li>visual XML Editor, not really WYSIWYG, limited user experience</li>
</ul></li>
<li><a href="http://dep4e.sourceforge.net/" class="external">DocBook Editing and Processing for Eclipse (DEP4E)</a> DEP4E integrates DocBook XML and DocBook XSL into Eclipse IDE to create, edit and process DocBook projects.
<ul>
<li>DocBook</li>
<li>OpenSource & free</li>
<li>no visual mode only pure XML editing</li>
</ul></li>
<li><a href="https://www.xmlmind.com/xmleditor/download.shtml" class="external">XMLmind XML Editor Personal Edition</a>
<ul>
<li>DocBook</li>
<li>DITA</li>
<li>Can import DOCX and splits it up into topics - excellent!</li>
<li>free but closed source</li>
<li>WYSIWYG</li>
</ul></li>
<li><a href="http://codex.ca/download.html" class="external">Codex</a> WYSIWYG DITA Editor
<ul>
<li>DITA</li>
<li>Free License, closed source</li>
<li>WYSIWYG</li>
</ul></li>
<li><a href="https://www.oxygenxml.com/xml_editor/docbook_editor.html" class="external">Oxygen</a>
<ul>
<li>DocBook, DITA</li>
<li>Academic license: $99</li>
<li>WYSIWYG (excellent!)</li>
</ul></li>
<li>OpenOffice
<ul>
<li>OpenSource & free</li>
<li>real WYSIWYG</li>
<li>DocBook: The ability to operate with DocBook files was added to Apache OpenOffice 3.4.1 as experimental feature (Dec 2015) (<a href="https://www.openoffice.org/xml/xmerge/docbook/">https://www.openoffice.org/xml/xmerge/docbook/</a>) (<a href="https://web.archive.org/web/20121226165205/http://www.openoffice.org/xml/xmerge/docbook">https://web.archive.org/web/20121226165205/http://www.openoffice.org/xml/xmerge/docbook</a>). Problems with this functionality exist, see <a href="https://forum.openoffice.org/en/forum/viewtopic.php?f=7&t=93593&p=445548">https://forum.openoffice.org/en/forum/viewtopic.php?f=7&t=93593&p=445548</a>
<ul>
<li>Sources for the xsl files are at <a href="https://github.com/LibreOffice/core/tree/master/filter/source/docbook">https://github.com/LibreOffice/core/tree/master/filter/source/docbook</a></li>
</ul></li>
<li>DITA: Can open DITA files but support is limited, not the full DITA spec seems to be supported. (Images missing, text formatting missing) no support for `<em>.ditamap</em> files</li>
</ul></li>
<li><a href="https://www.adobe.com/products/robohelp.html" class="external">Adobe RoboHelp</a> can open/import DITA, operates internally with another format, export of eclipse help possible.</li>
</ul>
<p>See also:</p>
<ul>
<li><a href="https://www.ditawriter.com/dita-related-tools/">https://www.ditawriter.com/dita-related-tools/</a></li>
</ul>
<a name="DocBook"></a>
<h3 >DocBook<a href="#DocBook" class="wiki-anchor">¶</a></h3>
<p>DocBook mainly because this document type uses self-descriptive names for its elements: para for a paragraph, itemizedlist of an itemized list, ....</p>
<p>Specific parts of a chapter can be included and repeating of the same content at various places is possible. So called xml-catalog-files map virtual to real file locations. This could for example be useful to provide the location of release/develop files. </p>
<p>The excellent site <a href="http://www.stefan-rinke.de/articles/publish/index.html" class="external">DocBook-Publishing</a> provides a framework for creating and publishing DocBooks. This framework includes the option to convert odt files into DocBook xml files. The tool for this transformation, <a href="http://ebellot.chez.com/ooo2sdbk/" class="external">OOo2sDbk</a>, is being developed by Eric Bellot. This however only supports the conversion in one direction.</p>
<hr>
<a name="Experimental-workflows"></a>
<h2 >Experimental workflows<a href="#Experimental-workflows" class="wiki-anchor">¶</a></h2>
<p><strong>Converting Word (docx) to DocBook</strong></p>
<p><a href="https://github.com/docbook/wiki/wiki/ConvertOtherFormatsToDocBook">https://github.com/docbook/wiki/wiki/ConvertOtherFormatsToDocBook</a></p>
<p><strong>ooo2dbk</strong> is also available as package in debian and derivates. The source package can be downloaded from <a href="https://launchpad.net/ubuntu/+source/ooo2dbk/2.1.0-1.1">https://launchpad.net/ubuntu/+source/ooo2dbk/2.1.0-1.1</a>.<br>
Processing of OpenOffice 2 files (odt) requires the ooo2dbk.odf.xsl which can be extracted from the source package. Copy this file to <code>/usr/share/xml/ooo2dbk/</code>task <a class="issue tracker-6 status-5 priority-11 priority-default closed" title="task: Evaluate document format and management for the documentation (Closed)" href="https://dev.e-taxonomy.eu/redmine/issues/8555">#8555</a>: Evaluate document format and management for the documentation - EDIT Platform Etablierung - Redmine<br>
change the files location which is configured in <code>/etc/ooo2dbk.xml</code>. </p>
<p><strong>Potential workflow to convert docx files into modularized DocBook xml files</strong></p>
<p>Tools:</p>
<ul>
<li>LibreOffice Writer (Version: 6.0.7.3)
<ul>
<li>Extract embedded images and replace embedded images with linked images: <a href="https://extensions.libreoffice.org/extensions/extract-embedded-images-and-replace-embedded-images-with-linked-images-picextract" class="external">PicExtract - 1.0</a></li>
</ul></li>
</ul>
<p>Process:</p>
<ol>
<li>Open the docx file in Writer and save as odt</li>
<li>Open the odt file</li>
<li>Stop "Track Changes" and Disable "Show track changes", save</li>
<li>In the toolbar click "PicExtract" <img src="https://dev.e-taxonomy.eu/redmine/attachments/download/1716/picture566-1.png" alt="" /> which is available once the PicExtract module is installed.</li>
<li>The dialog will offer to create <code>Pictures/</code> of the document location. We accept this setting and check both options below:
<ul>
<li>[x] use image/object names ...</li>
<li>[x] replace embedded</li>
</ul></li>
<li>The extraction process may fail at some point with the notification that the document must be saved first. If this happens save the ddt and try again. If this does not help, save the odt as DocBook xml and search the xml file for <code><inlinegraphic fileref="embedded:</code> the image named after that string needs to be exported manually by saving and linking to the image via the Image Properties dialog. Now you can try again to run the extraction process. Repeat these steps until the extraction completes without warning.</li>
<li>The final XML file needs to be post processed:
<ul>
<li>replace all <code>fileref="#Pictures</code> by <code>fileref="Pictures</code> to fix the boken image links</li>
<li>....</li>
</ul></li>
</ol>