Seminar openCode – Dokumentation mit GitLab Pages, easyPDF und easyWebsite

Aktuelle Dokumentation erleichtert die Nachnutzung von Software und die Zusammenarbeit zwischen Organisationen. Das Seminar zeigt, wie Inhalte in einem openCode-Projekt versioniert gepflegt und über vorbereitete Veröffentlichungsabläufe als Website und PDF ausgegeben werden. Die Redaktion arbeitet mit Markdown, nachvollziehbaren Änderungsvorschlägen und klaren Freigabeschritten. Technische Generierung und redaktionelle Qualität werden gemeinsam betrachtet, damit Veröffentlichungen verständlich, auffindbar und zuverlässig pflegbar bleiben.

Die Übungen verwenden eine kleine Projektdokumentation mit Text, Tabelle und Abbildung. Daraus werden eine GitLab-Pages-Website, eine Ausgabe mit easyWebsite und eine PDF mit easyPDF erstellt. Neben der technischen Ausführung werden Überschriftenstruktur, Navigation, Lesereihenfolge, Bildbeschreibungen und die Darstellung von Tabellen untersucht. Die Werkzeuge unterstützen zugängliche Ausgaben; eine automatische Erstellung allein belegt jedoch nicht, dass sämtliche inhaltlichen und technischen Anforderungen an Barrierefreiheit erfüllt sind. Die notwendige manuelle Kontrolle wird daher ausdrücklich in den Redaktionsablauf eingebaut.

Inhaltsübersicht

1. Dokumentationsstruktur und Markdown
2. GitLab Pages veröffentlichen
3. Webausgabe mit easyWebsite
4. PDF-Ausgabe mit easyPDF
5. Redaktion und Veröffentlichungsqualität

1. Dokumentationsstruktur und Markdown

• Lesergruppen, Informationsbedarf und Dokumentationsarten festlegen; Projektübersicht, Nutzung und Betrieb sinnvoll gliedern.
• Überschriften, Listen, Tabellen, Codeblöcke und Abbildungen in Markdown konsistent einsetzen.
• Redaktionsregeln für Dateistruktur, Benennung, Bildbeschreibungen und wiederkehrende Inhalte vereinbaren.

Praxisübung: Ein ungeordnetes Beispieldokument in eine verständliche Markdown-Struktur überführen und fehlende Beschreibungen ergänzen.

2. GitLab Pages veröffentlichen

• Statische Inhalte und die bereitgestellte Seitenvorlage einordnen; Navigation, Seitentitel und Dokumentationsstruktur konfigurieren.
• Die vorhandene Pages-Pipeline nachvollziehen, einen Lauf prüfen und den veröffentlichten Stand dem richtigen Commit zuordnen.
• Erreichbarkeit und Sichtbarkeit der Website gesondert prüfen; vertrauliche Inhalte vor einer öffentlichen Ausgabe erkennen.

Praxisübung: Eine vorbereitete Pages-Vorlage anpassen, zwei Inhaltsseiten ergänzen und Navigation sowie tatsächliche Veröffentlichung im Browser prüfen.

3. Webausgabe mit easyWebsite

• Markdown-Inhalte in die bereitgestellte easyWebsite-Struktur übernehmen und die unterstützten Gestaltungsoptionen einordnen.
• Navigation, Suche und das verwendete Designsystem auf die Informationsstruktur abstimmen.
• Optionale Zusatzdienste wie die Rückmeldung aus der Webansicht von den vorhandenen Grundfunktionen unterscheiden.

Praxisübung: Die Projektdokumentation als Website erzeugen und Überschriftenfolge, Tastaturbedienung und Lesbarkeit an ausgewählten Stellen überprüfen.

4. PDF-Ausgabe mit easyPDF

• Die vorbereitete easyPDF-Konfiguration verwenden, Dokumentmetadaten pflegen und aus dem Markdown-Bestand eine PDF erzeugen.
• Tags, Überschriften, Tabellen und Bildbeschreibungen in der PDF prüfen; Lesereihenfolge und Struktur mit geeigneten Werkzeugen untersuchen.
• Automatische Prüfbefunde von inhaltlichen Anforderungen unterscheiden und fehlerhafte Ausgangsinhalte gezielt verbessern.

Praxisübung: Eine PDF mit absichtlich unvollständiger Bildbeschreibung erzeugen, den Mangel beheben und die korrigierte Ausgabe erneut kontrollieren.

5. Redaktion und Veröffentlichungsqualität

• Änderungsvorschläge, redaktionelle Gegenprüfung und einen eindeutig gekennzeichneten Veröffentlichungsstand zusammenführen.
• Web- und PDF-Ausgabe auf Konsistenz, Versionsangabe, Navigation und vollständige Inhalte vergleichen.
• Zuständigkeiten, Freigabekriterien und wiederkehrende Kontrollen für die laufende Dokumentationspflege festlegen.

Praxisübung: Eine Dokumentationsänderung durch Review und Freigabe führen, beide Ausgabeformate erzeugen und deren Übereinstimmung anhand einer Checkliste prüfen.

Schulungsumgebung

Der Kunde stellt ein berechtigtes Übungsprojekt mit funktionierenden Vorlagen für GitLab Pages, easyPDF und easyWebsite sowie Browser und PDF-Prüfwerkzeuge bereit. Sämtliche Übungsinhalte und Bilder sind zur vorgesehenen Ausgabe freigegeben. Optionale Feedbackdienste werden nur bei bereitgestellter Freischaltung praktisch genutzt.