Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- CERN-HSF
- Technischer Redakteur:
- SabitaR
- Projektname:
- Restrukturierung und Optimierung der Allpix Squared-Dokumentation
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
ÜBERSICHT Ich habe mich aus zwei Hauptgründen für das Allpix Squared-Projekt des CERN-HSF entschieden:
Weiterbildung: Die bestehende Dokumentation dieses Projekts ist umfassend und umfasst mehrere Inhaltsformate. Das Prüfen und Umstrukturieren dieser umfangreichen Dokumentensammlung wird mir dabei helfen, meine Informationsarchitektur und meine Schreibfähigkeiten zu verbessern. Außerdem ist der Projektbereich (Teilchenphysik!) neu für mich. Es fordert mich heraus, meine Fähigkeiten zur Interaktion als Entwickler zu verbessern. Ich bin der Meinung, dass technische Redakteure Informationen von Entwicklern verarbeiten und nützliche Inhalte für Nutzer jeder Ebene präsentieren können, WENN wir unsere erforderliche Hintergrundrecherche 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 auf meiner To-Learning-Liste ganz oben steht. Ich freue mich darauf, mehr über den LaTeX-Markdown-Hugo-GitLab-CI-Workflow zu erfahren.
Während der Erkundungsphase des technischen Redakteurs habe ich mich kurz mit den Mentoren des Projekts ausgetauscht und mich mit der bestehenden Struktur der Dokumente vertraut gemacht. Ich habe auch eine Demo-Website erstellt (https://ap2-demo.netlify.app/), um zu testen, ob ich Hugo und Docsy auf meinem Windows-Computer richtig konfigurieren kann. Ich konnte die Website auf Netlify bereitstellen, aber nicht auf Gitlab-Seiten. Damit dieses Projekt seinen aktuellen Bereitstellungsworkflow beibehalten kann, werde ich das Hugo Docsy-Design auf Gitlab-Seiten bereitstellen.
ERWARTETE PROJEKTERGEBNISSE - Eine optimierte Projektwebsite mit Dokumentation, Code, Tutorials und Neuigkeiten. - Ein umstrukturiertes und geprüftes Nutzerhandbuch, in dem für Nutzer und Entwickler vorgesehene Inhalte getrennt voneinander aufgeführt sind und zuvor fehlende Informationen enthalten sind - Ein Tutorial-Workflow mit verfügbaren Beispielen für die Dokumentation mit Anleitungen, häufig gestellten Fragen und häufig auftretenden Problemen
PROJEKTTOOLS Die aktuelle Dokumentation von Allpix Squared verwendet neben GitLab und Gitlab CI auch LaTeX, Doxygen, pandoc und Hugo. Die Projektmentoren und ich haben uns darüber unterhalten, ob Inhalte mit MathJax-Plug-ins von LaTeX zu Markdown verschoben werden könnten. Wenn ich erfolgreich bin, umfasst der Dokument-Workflow Hugo, Markdown, Doxygen, Git und Gitlab CI. Damit die Tutorials auf derselben Website/Plattform bleiben, verwende ich Hugo und Markdown. Ich bin neugierig, ob Codelabs-as-a-Tool (ClaaT) für Tutorials verwendet werden kann. Diesen Juli möchte ich den ClaaT-Hugo-Workflow testen und ihn mit den Mentoren besprechen, die ausgewählt werden.
PROJEKTDAUER Ich möchte das Allpix Squared-Projekt innerhalb der üblichen drei Monate (14. September 2020 bis 30. November 2020) fertigstellen. In dieser Zeit werde ich etwa 15 Stunden pro Woche dafür aufwenden. Zu diesen Zeiten gehören Mentorensitzungen und bei Bedarf zugehörige E-Mails. Ich werde auch die GSoD-Zeitpläne für die Community-Bindung und den Projektabschluss einhalten.
AUFGABEN Optionen recherchieren, besprechen und erkunden (17. August bis 13. September 2020): – Projektanforderungen verstehen – Software Allpix Squared installieren, um ggf. fehlende Informationen in den aktuellen Dokumenten zu finden - Fordern Sie die erforderlichen Anmeldedaten an. - Nutzer-Workflows für verschiedene Nutzer von Allpix Squared erstellen - Inhalte nach Nutzerrolle klassifizieren - Auswirkungen der Konvertierung von LaTeX-Dateien in Markdown prüfen - Quell-Repositories konsolidieren oder mit mehreren Git-Repositories arbeiten - Bonus: CLaaT als Option für Anleitungen testen - Bonus: Erstellung eines kurzen Style-Leitfadens/Kurzcodes für Beitragende: Unterstützung bei der Pflege von Dokumenten in der Community
Inhalte umstrukturieren, überprüfen und optimieren (14. September bis 19. Oktober 2020): Zwei Aufgaben pro Woche, etwa 5–7 Stunden pro Aufgabe. Dieser Zeitplan beinhaltet eine Pufferwoche zur Bewältigung unerwarteter Verzögerungen oder Probleme.
- Vorhandene Inhalte und Nutzerklassifizierungen unter Berücksichtigung der Nutzerworkflows überprüfen
- Einen Workflow für neu strukturierte 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
- PDF-Dateien der Nutzer- und Entwicklerleitfäden generieren
- Bonus: Strukturieren Sie Inhalte für Tutorials anhand von Beispielen und Problemen.
- Bonus: Richten Sie einen Tutorial-Workflow für Anleitungsbeispiele ein Zeitplan: 5 Wochen (Entwicklungsphase des Dokuments)
Website erstellen (19. Oktober bis 30. November 2020): 1–2 Aufgaben pro Woche, ca. 5–7 Stunden pro Aufgabe. Dieser Zeitplan umfasst eine Pufferwoche zur Behebung von Problemen und zur Feinabstimmung des Endergebnisses.
- Veröffentlichungs-Workflow verstehen und testen
- Website-Struktur mit Hugo und Docsy erstellen
- Mit Docsy die aktuelle automatische Bereitstellung und den aktuellen Workflow testen
- Inhalte aus Doxygen abrufen
- Bedienungsanleitungen, Entwicklerhandbücher und Anleitungen aus LaTex- oder Markdown-Inhalten entwickeln
- Erscheinungsbild der Projektwebsite fertigstellen (Logo, Farben, Vorlage, Layout, Links, Nutzerfreundlichkeit und Gitlab-CI/CD) Zeitplan: 6 Wochen (Entwicklungsphase des Dokuments)