Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Le langage julia
- Rédacteur technique:
- mkg33
- Nom du projet:
- La documentation unifiée sur le machine learning scientifique
- Durée du projet:
- Exécution longue (5 mois)
Project description
J'aimerais travailler à l'unification de l'organisation SciML, car il y a beaucoup de possibilités d'amélioration dans ce domaine. La réalisation de ce projet offrira sans aucun doute des avantages immédiats aux programmeurs Julia et aux contributeurs/maintenants actifs de SciML. Les packs dispersés dans SciML offrent des outils très utiles, mais il y a toujours un risque qu'ils ne soient pas remarqués (surtout par les nouveaux venus), simplement parce que l'utilisateur n'a pas été en mesure de découvrir le pack et de l'appliquer à son problème.
C'est assez frustrant, car l'objectif principal des packages est d'atteindre un large public de programmeurs (aussi bien les débutants que les experts). Afin d'éviter la situation décrite ci-dessus, je propose de revoir en profondeur la "première page" de la documentation SciML et de créer une sorte de hub que les utilisateurs pourraient utiliser pour parcourir les packages associés et explorer l'écosystème en pleine croissance. Il peut également servir de point de référence précieux pour les utilisateurs plus expérimentés et leur permettre de travailler plus efficacement.
Tout d'abord, la documentation existante de tous les packages individuels doit être révisée en tenant compte des problèmes stylistiques les plus élémentaires (tels que l'orthographe, la ponctuation, la grammaire, etc.). Pour assurer la cohérence stylistique, SciML doit disposer d'un guide de style concret (indispensable pour effectuer des modifications rétrospectives et pour référence ultérieure). Ce serait une perte de temps de repartir de zéro. Il devrait plutôt être basé sur les conventions existantes de Julia et inclure de nouveaux entiers pour les problèmes spécifiques à SciML.
Une fois le guide de style terminé, j'ai l'intention de réviser la documentation actuelle lors de la deuxième phase du projet. Cela rendra la documentation plus professionnelle et stable. J'ai déjà créé plusieurs demandes d'extraction pour illustrer mon approche de cette tâche. Au cours de cette phase, j'ai également l'intention de concevoir (et de mettre en œuvre) un système de citation efficace. La toute première tâche consistera à mettre à jour la page des citations obsolètes.
La troisième phase, sans doute la plus importante, consistera à concevoir la feuille de route SciML, qui mettra l'accent sur l'interaction entre les packs dispersés. Plus la cohésion entre deux packs est forte (en ce qui concerne le problème ou le code lui-même), plus ils doivent apparaître dans la liste "voir aussi". Je propose de créer deux clés de recommandation: une pour la similarité du code et l'autre pour la similarité des problèmes. De cette façon, les utilisateurs pourraient identifier d'autres packages potentiellement utiles beaucoup plus rapidement qu'en parcourant les référentiels et la documentation respectifs. Au lieu de lister toutes les connexions possibles entre les packs, je préférerais me concentrer sur les plus grands et essayer de présenter leurs liens avec des packages plus petits (cette méthode sera également étendue à la mise à jour des tutoriels où la connexion avec un autre pack doit être indiquée). Cette approche garantit que les listes "voir aussi" seront informatives sans constituer des énumérations exhaustives de combinaisons de packages.