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:
- Die Julia Language
- Technischer Redakteur:
- mkg33
- Projektname:
- Die einheitliche Dokumentation von wissenschaftlichem Machine Learning
- Projektdauer:
- Langfristig (5 Monate)
Projektbeschreibung
Ich möchte an der Vereinheitlichung der SciML-Organisation arbeiten, da es in diesem Bereich viel Raum für Verbesserungen gibt und der Abschluss dieses Projekts zweifellos unmittelbare Vorteile sowohl für Julia-Programmierer als auch für aktive Mitwirkende/Verwalter von SciML bieten wird. Die in SciML verteilten Pakete bieten einige wirklich nützliche Tools, aber es besteht immer die Gefahr, dass sie unbemerkt bleiben (insbesondere von Neueinsteigern), weil der Nutzer das Paket nicht finden und auf das vorliegende Problem anwenden konnte.
Das ist ziemlich frustrierend, da der Hauptzweck der Pakete darin besteht, eine große Zielgruppe von Programmierern (Anfänger und Experten gleichermaßen) zu erreichen. Um die oben beschriebene Situation zu vermeiden, schlage ich vor, die Titelseite der SciML-Dokumentation gründlich zu überarbeiten und eine Art Hub zu erstellen, über den Nutzer verwandte Pakete durchsuchen und das wachsende Ökosystem erkunden können. Er kann aber auch als Referenz für erfahrene Nutzende dienen und ihnen helfen, effizienter zu arbeiten.
Zunächst muss die bestehende Dokumentation aller einzelnen Pakete im Hinblick auf grundlegende stilistische Aspekte wie Rechtschreibung, Zeichensetzung und Grammatik überarbeitet werden. Um stilistische Einheitlichkeit zu gewährleisten, muss SciML über einen konkreten Styleguide verfügen (unverzichtbar für retrospektive Änderungen und für eine zukünftige Referenz). Es wäre Zeitverschwendung, ganz von vorn anzufangen. Stattdessen sollte sie auf den bestehenden Julia-Konventionen basieren und neue Komplettlösungen für SciML-spezifische Probleme enthalten.
Sobald der Styleguide fertiggestellt ist, habe ich vor, die aktuelle Dokumentation in der zweiten Phase des Projekts zu überarbeiten. Dadurch sieht die Dokumentation professioneller und stabiler aus. Ich habe bereits mehrere Pull-Anfragen erstellt, die meine Herangehensweise an diese Aufgabe veranschaulichen. In dieser Phase beabsichtige ich außerdem, ein effizientes Zitationssystem zu entwickeln (und zu implementieren). Die erste Aufgabe besteht darin, die Seite mit veralteten Zitationen zu aktualisieren.
Die dritte Phase, die wohl wichtigste, besteht darin, die SciML-Roadmap zu entwerfen, die das Zusammenspiel zwischen den verstreuten Paketen betont. Je stärker der Zusammenhang zwischen zwei Paketen ist (in Bezug auf das Problem oder den Code selbst), desto näher sollten sie in der Liste „Siehe auch“ stehen. Ich schlage vor, zwei Empfehlungsschlüssel zu erstellen: einen für die Codeähnlichkeit und einen für die Ähnlichkeit von Problemen. Auf diese Weise könnten die Benutzer andere potenziell nützliche Pakete viel schneller identifizieren, als wenn sie die jeweiligen Repositories und die Dokumentation mühsam durchsuchen würden. Anstatt alle möglichen Verbindungen zwischen den Paketen aufzulisten, konzentriere ich mich lieber auf die größeren und versuche, deren Links mit kleineren Paketen zu präsentieren (diese Methode wird auch auf die Aktualisierung von Anleitungen erweitert, bei denen die Verbindung mit einem anderen Paket hervorgehoben werden sollte). Dieser Ansatz stellt sicher, dass die Listen mit der Option „siehe auch“ informativ sind, ohne dass es sich dabei um vollständige Aufzählungen von Paketkombinationen handelt.