Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- CERN-HSF
- Technischer Redakteur:
- SabitaR
- Projektname:
- Neustrukturierung und Optimierung der Allpix Squared-Dokumentation
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
ÜBERBLICK Ich habe das Allpix Squared-Projekt des CERN-HSF aus zwei Hauptgründen ausgewählt:
Kompetenzaufbau: Die bestehende Dokumentation dieses Projekts ist umfassend und integriert mehrere Inhaltsformate. Durch die Analyse und Umstrukturierung dieser umfangreichen Dokumentensammlung kann ich meine Kenntnisse in Informationsarchitektur und Schreiben verbessern. Außerdem ist mir die Projektdomain (Teilchenphysik!) neu. Ich kann meine Fähigkeiten im Umgang mit Entwicklern verbessern. Ich glaube, dass technische Redakteure den Input von Entwicklern verarbeiten und nützliche Inhalte für Nutzer auf allen Ebenen präsentieren können, WENN wir die erforderlichen Recherchen durchführen und die richtigen Fragen stellen. Mit diesem Projekt kann ich diese Theorie testen.
Technisches Know-how: Für dieses Projekt ist Hugo erforderlich – ein Tool, das ganz oben auf meiner Liste der zu erlernenden Tools steht. Ich freue mich darauf, den LaTeX-Markdown-Hugo-GitLab-CI-Workflow kennenzulernen.
Während der Erkundungsphase des technischen Redakteurs habe ich mich kurz mit den Projektmentoren ausgetauscht und mich mit der bestehenden Struktur der Dokumentensuite vertraut gemacht. Außerdem habe ich eine Demo-Website (https://ap2-demo.netlify.app/) erstellt, um zu testen, ob ich Hugo und Docsy auf meinem Windows-Computer richtig konfigurieren kann. Ich konnte die Website in Netlify bereitstellen, aber nicht auf Gitlab-Seiten. Damit dieses Projekt seinen aktuellen Bereitstellungsablauf beibehalten kann, finde ich eine Möglichkeit, das Hugo Docsy-Design auf Gitlab Pages bereitzustellen.
ERFORDERLICHE PROJEKTERGEBNISSE: Eine optimierte Projektwebsite mit Dokumentation, Codereferenz, Anleitungen und Neuigkeiten. – Ein überarbeitetes und neu strukturiertes Benutzerhandbuch, das Inhalte für Nutzer und Entwickler voneinander trennt und zuvor fehlende Informationen enthält. – Einen Workflow mit Anleitungen aus verfügbaren Beispielen für Anleitungen, FAQs und häufig auftretende Probleme.
PROJEKTTOOLS Für die aktuelle Dokumentation von Allpix Squared werden neben GitLab und Gitlab CI auch LaTeX, Doxygen, pandoc und Hugo verwendet. Die Projektmentoren und ich haben darüber gesprochen, ob wir Inhalte mit MathJax-Plug-ins von LaTeX in Markdown konvertieren könnten. Wenn ich Erfolg habe, umfasst der Dokumentworkflow dann Hugo, Markdown, Doxygen, git und Gitlab CI. Damit die Anleitungen auf derselben Website/Plattform verfügbar sind, verwende ich Hugo und Markdown. Ich bin neugierig, ob die Verwendung von Codelabs-as-a-Tool (ClaaT) für Tutorials möglich ist. Im Juli hoffe ich, den ClaaT-Hugo-Workflow zu testen und ihn mit den Mentoren zu besprechen, falls ich ausgewählt werde.
PROJEKTDAUER Ich möchte das Allpix Squared-Projekt innerhalb des standardmäßigen dreimonatigen Zeitraums (14. September 2020 - 30. November 2020) abschließen. In diesem Zeitraum werde ich etwa 15 Stunden pro Woche dafür aufwenden. Diese Stunden umfassen gegebenenfalls Mentorengespräche und zugehörige E-Mails. Ich werde auch die Zeitpläne für die Community-Bindung und die Projektfinalisierung einhalten.
PROJEKTAUFGABEN So möchte ich meine vorgeschlagenen Änderungen an der vorhandenen Allpix Squared-Dokumentensuite implementieren: 1. Recherche, Diskussion und Erkundung von Optionen (17. August bis 13. September 2020): - Projektanforderungen ermitteln - Allpix Squared-Software installieren, um fehlende Informationen in den aktuellen Dokumenten zu identifizieren. – Die erforderlichen Anmeldedaten anfordern. – Nutzerworkflows für verschiedene Nutzer von Allpix Squared erstellen – Inhalte nach Nutzerrolle klassifizieren – Die Auswirkungen der Umwandlung von LaTeX-Dateien in Markdown prüfen – Quell-Repositories konsolidieren oder die Arbeit mit mehreren Git-Repositories kennenlernen – Bonus: CLaaT als Option für Anleitungen testen – Bonus: Einen kurzen Styleguide/eine kurze Referenz für Kurzcodes erstellen, um Mitwirkenden bei der Pflege von Dokumenten zu helfen Zeitplan: Phase des Aufbaus von Community-Bindungen
Inhalte neu strukturieren, überprüfen und optimieren (14. September bis 19. Oktober 2020): Zwei Aufgaben pro Woche, ca. 5–7 Stunden pro Aufgabe. Dieser Zeitplan umfasst eine Pufferwoche für unerwartete Verzögerungen oder Probleme.
- Vorhandene Inhalte und Nutzerklassifizierungen im Hinblick auf Nutzerworkflows überprüfen
- Workflow für umstrukturierte Inhalte für verschiedene Nutzer skizzieren und testen
- Fehlende Inhalte finden und optimieren
- LaTeX-Dateien in Markdown konvertieren
- Inhaltsverzeichnis des Nutzerhandbuchs und des Entwicklerhandbuchs fertigstellen
- PDFs der Anleitungen für Nutzer und Entwickler generieren
- Bonus: Inhalte für Anleitungen anhand von Beispielen und Problemen strukturieren
- Bonus: Einen Workflow für Anleitungen mit Beispielen einrichten Zeitplan: 5 Wochen (Phase der Dokumententwicklung)
Website erstellen (19. Oktober bis 30. November 2020): 1–2 Aufgaben pro Woche, ca. 5–7 Stunden pro Aufgabe. Dieser Zeitplan umfasst eine Pufferwoche, um Probleme zu beheben und die endgültige Ausgabe zu optimieren.
- Veröffentlichungsablauf kennenlernen und testen
- Websitestruktur mit Hugo und Docsy erstellen
- Mit Docsy testen, wie die aktuelle automatische Bereitstellung und der Workflow beibehalten werden
- Inhalte aus Doxygen abrufen
- Bedienungsanleitungen, Entwicklerhandbücher und Anleitungen aus Markdown- oder LaTeX-Inhalten erstellen
- Erscheinungsbild der Projektwebsite fertigstellen (Logo, Farben, Vorlage, Layout, Links, Nutzerfreundlichkeit und Gitlab CI/CD) Zeitplan: 6 Wochen (Dokument-Entwicklungsphase)