Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- ScummVM
- Rédacteur technique:
- b-gent
- Nom du projet:
- Améliorer la documentation du code source via Doxygen
- Durée du projet:
- Durée standard (trois mois)
Project description
La documentation actuelle de l'API ScummVM (code source) est disponible ici: https://doxygen.scummvm.org/modules.html
Malheureusement, il est insuffisant dans de nombreux domaines:
1) Il n'y a pratiquement aucune structure, toutes les informations flottent au même niveau.
2) Les éléments C++ ne sont pas documentés de manière cohérente, et certains ne le sont même pas du tout. L'organisation mentionne cela comme l'un de ses principaux problèmes.
3) Des contenus obsolètes et obsolètes s'affichent toujours dans le résultat.
4) Le langage et l'utilisation des balises doxygen doivent être plus cohérents. Pour ce faire, vous avez besoin d'un ensemble de règles qui pourraient servir de base à un futur guide de style de documentation pour ce projet.
5) Le CSS doxygen utilisé sur cette page pourrait être amélioré pour le rapprocher du site Web de ScummVM: https://www.scummvm.org
Tous ces problèmes peuvent être résolus lors du projet de la saison des documents.
Cette application de la saison des documents est accompagnée d'une ébauche de PR que j'ai ouverte dans le projet pour illustrer certaines améliorations potentielles que je propose : https://github.com/scummvm/scummvm/pull/2361 Consultez la description pour en savoir plus sur son contenu et afficher la différence.
Voici à quoi ressemble la publication:
1) Je pense que ce qui est le plus déroutant pour les nouveaux contributeurs potentiels, et en général pour tous ceux qui consultent la documentation de l'API actuelle, est le manque de structure. L'introduction d'une documentation structurée des API améliorerait la lisibilité, la visibilité et, par conséquent, la facilité d'utilisation du lot de documents. C'est pourquoi ma demande de publication introduit des groupes doxygen dans tous les fichiers d'en-tête du dossier "common". Avec cette nouvelle structure, si quelqu'un veut trouver des documents pour l'API liée au système d'exploitation (par exemple), il peut facilement les trouver dans la navigation.
2) Un nouveau fichier de configuration doxygen est configuré pour permettre la création de cette documentation.
3) Un fichier "links.doxyfile" à partir duquel tous les liens utilisés dans l'ensemble de documents peuvent être issus d'une seule source. Mécanisme utile lorsque vous travaillez avec doxygen.
4) Un CSS doxygen modifié. Elle provient actuellement d'un autre projet Open Source et n'est qu'un point de départ. Idéalement, l'apparence de la page doxygen doit être plus ou moins cohérente avec celle de la page Web de ScummVM.
Le communiqué de presse ne couvre pas le contenu lui-même, mais il doit absolument être travaillé. En d'autres termes, il s'agit d'identifier les parties essentielles du code qui ne sont pas documentées, celles qui ne sont pas suffisamment documentées ou les parties obsolètes du code qui doivent être supprimées de la documentation. Comme je n'ai jamais travaillé sur ce projet auparavant, le conseil d'un mentor sera nécessaire pour y parvenir.
Bien sûr, nous discuterons avec l'entreprise pour savoir si nous allons implémenter quoi que ce soit de la communication. Je me suis dit que les actes parlent plus que les mots. J'ai donc décidé de montrer ce que je peux faire au lieu de simplement le décrire dans la demande.
L'entreprise a fourni le calendrier approximatif suivant pour ce projet : Semaine Tâche principale Semaine 0 (avant le 14/09) Discussion et examen de la proposition Semaine 1 (14/09) Configuration de la compilation Doxygen Semaine 2 (21/09) Actualisation de la peau Doxygen (faible priorité) Semaine 3 (28/09) Code commun : OSystem, FS, structures de données, chaînes, etc. Semaine 4 (05/10) Code commun - Suite Semaine 5 (12/10) Moteurs : code commun et exemple de moteur Semaine 6 (19/10) Graphiques Semaine 7 (26/10) Audio Semaine 8 (02/11) Vidéo, images Semaine 9 (09/11) Backends : plates-formes, graphiques, événements Semaine 10 (23/11) Backends - Suite Semaine 11 (30/11) Récapitulatif et soumission du projet
Le seul changement que je proposerais est de commencer par travailler sur la structure, comme nous l'avons déjà indiqué. Cela peut être fait au cours des semaines 1 et 2, avec la mise en place du développement de l'oxygène (qui est déjà généralement effectuée) et le rafraîchissement de la peau de Doxygen. Ensuite, je suis d'accord qu'il est plus logique d'examiner les différentes sections une par une avec le mentor pour identifier les problèmes et améliorer la documentation doxygen.
Je vois qu'il s'agit d'un projet de longueur standard, mais je suis sûr que d'autres améliorations liées à la documentation de l'API pourront être effectuées une fois le projet GSoD terminé. Par exemple, vous pouvez créer un guide de style de documentation et l'ajouter au wiki afin que les contributeurs sachent comment documenter le code qu'ils ajoutent.
Je me ferai un plaisir de vous aider à effectuer ce type de tâche une fois le GSoD terminé. Je suis sûr que ScummVM pourrait avoir besoin d'un rédacteur technique qui s'assurera que sa documentation API est de bonne qualité et facile à utiliser. Je vois également qu'il existe d'autres projets de documentation à venir sur lesquels je pourrais vous aider, comme la création d'un guide sur l'utilisation des plug-ins.