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:
- Die Programmiersprache Julia
- Technischer Redakteur:
- mkg33
- Projektname:
- Die einheitliche Dokumentation des wissenschaftlichen maschinellen Lernens
- Projektdauer:
- Langfristig (5 Monate)
Projektbeschreibung
Ich möchte an der Vereinheitlichung der SciML-Organisation mitarbeiten, da es in diesem Bereich viel Raum für Verbesserungen gibt und die Fertigstellung dieses Projekts zweifellos unmittelbare Vorteile sowohl für Julia-Programmierer als auch für aktive SciML-Mitarbeiter haben wird. Die in SciML verstreuten Pakete bieten einige wirklich nützliche Tools, aber es besteht immer die Gefahr, dass sie (insbesondere von Neulingen) unbemerkt bleiben, einfach weil der Nutzer das Paket nicht finden und auf das betreffende Problem anwenden konnte.
Das ist ziemlich frustrierend, da die Pakete in erster Linie ein breites Publikum von Programmierern (Anfängern und Experten gleichermaßen) ansprechen sollen. Um die oben beschriebene Situation zu vermeiden, schlage ich vor, die „Startseite“ der SciML-Dokumentation gründlich zu überarbeiten und eine Art Hub zu erstellen, über den Nutzer ähnliche Pakete durchsuchen und das wachsende Ökosystem erkunden können. Er kann auch als wertvoller Referenzpunkt für erfahrenere Nutzer dienen und ihnen die Arbeit erleichtern.
Zunächst einmal muss die bestehende Dokumentation aller einzelnen Pakete im Hinblick auf die grundlegendsten stilistischen Probleme (z. B. Rechtschreibung, Zeichensetzung, Grammatik) überarbeitet werden. Um stilistische Einheitlichkeit zu gewährleisten, muss SciML einen konkreten Styleguide haben (unentbehrlich für die Durchführung retrospektiver Änderungen und als Referenz für die Zukunft). Es wäre Zeitverschwendung, noch einmal von vorne anzufangen. Stattdessen sollte sie auf den vorhandenen Julia-Konventionen basieren und neue Einträge für SciML-spezifische Probleme enthalten.
Nach Fertigstellung des Styleguides beabsichtige ich, die aktuelle Dokumentation in der zweiten Phase des Projekts zu überarbeiten. Dadurch wirkt die Dokumentation professioneller und stabiler. Ich habe bereits mehrere Pull-Anfragen erstellt, die meine Herangehensweise an diese Aufgabe veranschaulichen. In dieser Phase möchte ich auch ein effizientes Zitatsystem entwickeln und implementieren. Der erste Schritt besteht darin, die Seite mit veralteten Zitationen zu aktualisieren.
Die dritte Phase, die wohl wichtigste, umfasst die Erstellung der SciML-Roadmap, in der das Zusammenspiel der verschiedenen Pakete hervorgehoben wird. Je stärker die Kohäsion zwischen zwei Paketen ist (im Hinblick auf das Problem oder den Code selbst), desto näher sollten sie in der Liste „Weitere Informationen“ erscheinen. Ich schlage vor, zwei Empfehlungsschlüssel zu erstellen: einen für die Codeähnlichkeit und einen für die Ähnlichkeit des Problems. So können Nutzer andere potenziell nützliche Pakete viel schneller finden, als wenn sie mühsam in den jeweiligen Repositories und der Dokumentation suchen müssten. Anstatt alle möglichen Verbindungen zwischen den Paketen aufzulisten, konzentriere ich mich lieber auf die größeren und versuche, ihre Verknüpfungen mit kleineren Paketen darzustellen. Diese Methode wird auch auf die Aktualisierung von Anleitungen ausgeweitet, in denen auf die Verbindung mit einem anderen Paket hingewiesen werden sollte. So wird sichergestellt, dass die „Weitere Informationen“-Listen informativ sind, ohne eine vollständige Aufzählung der Paketkombinationen zu sein.